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Preface 



The RT—11 Programmer's Reference Manual describes the programmed re- 
quests and subroutines that are available in the system macro library 
(SYSMAC.SML) and system subroutine library (SYSLIB.OBJ). It provides 
programming examples that show how to use programmed requests and 
subroutines. 

Chapter 1, Introduction to Advanced RT-11 Programming, describes the 
implementation and use of the programmed requests and the FORTRAN- 
callable subroutines. 

Chapter 2, Programmed Request Description and Examples, describes the 
individual programmed requests in detail. Program examples are included 
for each request. In addition, macros and subroutines that are used in im- 
plementing device handlers and interrupt service routines are described. 

Chapter 3, System Subroutine Description and Examples, describes in de- 
tail all the RT-11 FORTRAN-callable subroutines. This chapter also con- 
tains examples of the use of the calls to the system subroutine library. 

Appendix A, Display File Handler, describes the graphics support for the 
RT-11 operating system. Program examples are included to help you de- 
velop your own display program. 

Appendix B, System Macro Library, is a listing of the RT-11 System Macro 
Library (SYSMAC.SML). 

This manual is written for an advanced-level user. If you have no RT—11 
experience, or very little, read: 

Introduction to RT-11 

RT—11 System User's Guide 
Tjrr 1 1 c.„*^~, rr*,'7,w«„ ]i/f»„,.»7 

j.l>± — ±2. kjyoi/t:itL \^ LLi'Vi/ift^o xri.U'/C'Cf'U'C' 

PDP-11 MACRO-11 Language Reference Manual 

In addition, FORTRAN programmers should read: 

RT-11/RSTS/E FORTRAN rV User's Guide 
PDP-11 /FORTRAN Language Reference Manual 

If you are interested in additional programming techniques or other system 
programming topics, read the RT-11 Software Support Manual. 
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Chapter 1 

introduction to Advanced RT-11 Programming 

Programmed requests and system subroutines are available as part of the 
RT-11 Operating System and can aid you in writing reliable and efficient 
programs. 

Programmed requests provide a number of services to application pro- 
grams. The requests function as calls to routines in the RT-11 monitor that 
perform these services. As system macros, they are defined in a system 
macro library that is stored on the system volume and named SYS- 
MAC.SML. In addition, macro routines are available in the system macro 
library that can help you write device handlers and interrupt service 
routines. 

The file SYSMAC.MAC is not provided on the RT-11 distribution kit. How- 
ever, you will need this file if you want to modify the system macro library. 

You can create SYSMAC.MAC from the distributed file SYSMAC.SML by 
running the SPLIT utility. Type this CCL command: 

♦SPLIT ,SYSMAC.MAC=SYSMAC.SML/B: . .SYSM 

This command creates the file SYSMAC.MAC on your default device. The 
variable ..SYSM represents the boundary along which to split SYS- 
MAC.SML. Refer to the file CUSTOM.TXT on your distribution kit for the 
value to substitute for ..SYSM in the command line. Refer to the file UN- 
SUP.TXT for more information on using the SPLIT utility. 

If you are a FORTRAN programmer, you can access the RT-11 monitor 
services through calls to the system subroutine library called SYSLIB.OBJ, 
which is stored on the system volume. A character string manipulation 
package and two-word integer support routines are included in this library. 
The SYSLIB subroutines allov/ you to v/rite almost all application pro- 
grams in FORTRAN without having to do any assembly language coding. 

This chapter tells you how to use programmed requests and subroutines 
effectively in your programs. Examples are provided to demonstrate their 
flexibility and value in working programs. 



I.I rrogrammea nequesis 



You issue a programmed request in your source program when a certain 
monitor service is required. The programmed request expands into the ap- 
propriate machine language code during assembly time. During program 
execution, this code requests the resident monitor to supply the service 
represented by the programmed request. 
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The services involve the following processes: 

1. Initialization and control of operating system characteristics 

2. Allocating system resources and reporting status 

3. Command interpretation 

4. File operations 

5. Input/output operations 

6. Foreground/background communications 

7. Timer support 

8. Program termination or suspension 

9. System job communications 

10. Extended memory functions 

The system macro library (SYSMAC.SML) also contains several macros 
that are not programmed requests. These macros are provided to aid you in 
writing: 

1. Interrupt service routines 

2. Device handlers 

3. Memory management control blocks 

They are described in Chapter 2 along with the programmed requests. 

Components of the RT-11 Operating System that support programmed re- 
quests are as follows: 

1. Single- Job Monitor 

The single-job (SJ) monitor supports most of the programmed requests. 
Table 1-4 lists the programmed requests that are supported by the SJ 
monitor. These programmed requests can manipulate files, perform in- 
put and output, set timer routines, check system resources and status, 
and terminate program operations. 

2. Foreground/Background Monitor 

Some programmed requests are provided for the foreground/back- 
ground (FB) monitor only. Table 1-5 lists the programmed requests 
mat are supporLeu uy uit; ro iiiuiiitur iii auuitiuii lu Liiuae ixsmu iii 
Table 1-4. These programmed requests allow a program to set timer 
routines, suspend and resume jobs, and send messages and data be- 
tween foreground and background jobs. ' 

3. Extended Memory Monitor 

The extended memory (XM) monitor provides additional programmed 
requests and features above those found in the FB monitor. The XM 
monitor extends the memory support capability of RT-11 beyond the 
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28K-word (plus I/O page) restriction imposed by the 16-bit address size. 
The XM monitor's programmed requests extend a program's effective 
logical addressing space (see Table 1-5). 

4. Multiterminal Feature 

The multiterminal feature of RT-11 allows your program to perform 
character input/output on up to 16 terminals. Programmed requests are 
available to perform input/output, attach and detach a terminal for 
your program, set terminal and line characteristics, and return system 
status information. 

5. System Job Support 

System job support allows users in a foreground/background or ex- 
tended memory environment to extend the present standard 
foreground/background system to include up to eight jobs. Four system 
jobs are presently provided with the RT-11 system: the error logger, the 
device queue program (QUEUE), the transparent spooler package 
(SPOOL), and the communication package (VTCOM). Programmed re- 
quests allow programs to copy channels from other jobs, obtain job 
status information about jobs in the system, and send messages and 
data between any jobs in the system. The RT-11 Software Support 
Manual describes the system job feature in more detail. 

Programmed requests perform most system resource control and interroga- 
tion functions. However, some communication is accomplished by directly 
accessing two memory areas: the system communication area and the mon- 
itor fixed-offset area. 

The system communication area resides in locations 40 to 57(octal) and 
contains parameters that describe and control execution of the current job. 
This area holds information such as the Job Status Word, starting address 
of the job, User Service Routine (USR) swapping address, and the address of 
the start of the resident monitor. Some of this information is supplied by 
your program, while other data is supplied by the monitor and may not be 
changed. 

The second memory communication area, the fixed-offset area, is accessed 
by a fixed-address offset from the start of the resident monitor. This area 
contains system values used to control monitor operation. Your program 
can examine or modify these values to determine the condition of the opera- 
ting environment while a job is running. The RT-11 Software Support 
Manual describes in detail both the system communication area and the 
fixed-offset area. 

This manual specifically describes programmed requests for RT-11 Version 
5. Programmed requests for earlier versions of RT-11 and guidelines for 
their conversion are treated in Sections 1.1.4 and 1.1.5. 

1.1.1 Programmed Request Implementation 

1.1.1.1 EMT Instructions — A programmed request is a macro call followed 
by the necessary number of arguments. The macro code that corresponds to 
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the macro call of a programmed request is expanded by the MACRO assem- 
bler when the programmed request appears in your program. The expan- 
sion arranges the arguments of the programmed request for the monitor 
and generates an EMT (emulator trap) instruction. 

When an EMT instruction is executed, control passes to the monitor. The 
low-order byte of the EMT code provides the monitor with the information 
that tells it what monitor service is being requested. 

The execution of the EMT generates a trap through vector location 30. This 
vector location is loaded at boot time with an address pointing to a location 
in the monitor. The monitor location contains the EMT processing code that 
services the interrupt caused by the EMT instruction. 

Table 1-1 shows the codes that may appear in the low-order byte of an EMT 
instruction and the interpretation of these codes by the monitor. 

Table 1-1: EMT Codes 



Low-Order Byte Interpretation 



377 Reserved; RT-11 ignores this EMT and returns control to the 

user program immediately. 

376 Used internally by the RT-11 monitor; your programs should 

not use this EMT since its use would lead to unpredictable re- 
sults. 

375 Programmed request with several arguments; RO points to a 

block of arguments that supports the user request. 

374 Programmed request with one argument; RO contains a function 

code in the high-order byte and a channel code in the low-order 
byte. 

360-373 Used internally by the RT-11 monitor; your programs should 

never use these EMT codes since their use would lead to unpre- 
dictable results. 

340-357 Programmed requests with the arguments on the stack and/or 

inRO. 

0-337 Version 1 programmed requests with arguments both on the 

stack and in RO. They are supported for binary compatibility 
with Version 1 programs. 

EMT instructions should never appear in your programs except through 
program.med requests. 

1.1.1.2 System Control Path Flow — Figure 1-1 shows system flow when a 
programmed request is executed. 

In Figure 1-1, a programmed request in an application (or system utility) 
program is implemented with an EMT instruction. When your program is 
executed, the EMT instruction transfers control to the EMT processor code 
in the monitor. The user program counter (PC) and processor status word 
(PSW) are pushed onto the stack, and the contents of location 30 are placed 
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in the program counter. Location 30 points to the EMT processor code in 
the monitor. Location 32 contains the PSW for the EMT trap. Byte 52 of the 
system communication area is loaded with an error code by the monitor if 
the monitor detects any errors during the EMT processing. In addition, the 
EMT processor uses RO to pass back information to the program. All other 
registers except SP are preserved; .CSIGEN and .CSISPC return informa- 
tion on the stack. 

The monitor either processes a programmed request entirely when it is 
issued or it performs partial processing and queues the request for further 
processing. The requests that require queued processing support completion 
routines (see Section 1.1.3.5). If a request results in an error prior to being 
queued, the completion routine is not entered, and the monitor returns to 
the user program with the carry bit set. If the request is queued, the com- 
pletion routine is entered upon completion of further processing, regardless 
of the outcome. 

Figure 1-1: System Flow During Programmed Request Execution 
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1.1.2 System Conventions 

This section describes the system conventions that must be followed for the 
correct operation of programmed requests. 

1.1.2.1 Programmed Request Format — To issue programmed requests from 
assembly language programs, you must set up the arguments in correct 
order and issue the appropriate EMT instruction. Macros have been created 
to help you do this. They are contained in the system macro library named 
SYSMAC.SML. Their use is recommended for maintaining program com- 
patibility with future releases of RT-11 and for program readability. The 
macro names for all programmed requests except SOB start with a period 
(.) to distinguish them from symbols and macros you define. 

Arguments supplied to a programmed request must be valid assembler 
expressions since the arguments are used as source fields in the instruc- 
tions (such as a MOV instruction) when the macros are expanded at assem- 
bly time. All programmed requests that appear in your program must ap- 
pear in a .MCALL directive to make the macro definition available from 
the system macro library, SYSMAC.SML. If the programmed request is 
specified by a .MCALL directive, the programmed request is obtained from 
the system macro library at assembly time. Alternatively, you can enable 
the automatic .MCALL feature of MACRO by using the .ENABL MCL 
directive. 

Programmed requests have two formats that are accepted by the monitor. 
The first format specifies the programmed request followed by the argu- 
ments required by the request. The second format specifies the pro- 
grammed request, the address of the argument block, and the arguments 
that will be contained in the argument block. Because the way you can set 
up the argument block and specify arguments to a programmed request can 
vary, read the sections on programmed request format and on blank argu- 
ments to be sure of correct programmed request operation. 

FORMAT 1 

The first format for programmed requests is as follows: 

.PRGREQ Argl,Arg2,...,Argn 
where: 

.PRGREQ is the name of the programmed request 

Argl,Arg2,...,Argn are the arguments used with the request 

Programmed requests using this format generate either an EMT 374 in- 
struction or EMT 340 through 357 instructions. 

Programmed requests that use an EMT 374 instruction set up RO with the 
channel number in the even (low-order) byte and the function code in the 
odd (high-order) byte, as shown in Figure 1-2. 
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Figure 1-2: EMT 374 Argument 
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One programmed request that generates an EMT 374 is .DATE. The macro 
for this programmed request appears in the system macro Hbrary as: 

.MACRO .DATE 

MDU »*10.*-0^00 .'ZO 

EMT "D374 
.ENDM 

The function code, which in this case is lO(decimal) is placed in the high- 
order byte of RO. A channel code of is placed in the low-order bjiie. 

For EMT 340 through 357, if there are arguments, they are placed either 
on the stack, in RO, or in RO and on the stack. 

The programmed request .CSIGEN is an example of a programmed request 
that generates an EMT 344. A simplified macro expansion of this pro- 
grammed request is: 

.MACRO .CSIGEN DEMSPC .DEFEXT .CSTRNG .L INBUF 
.IIF NB <LINBUF> MOM LINBUF,-(B.) 

MOM DEySPC»-(B.) 
.IIF NB <LINBUF> INC (G. ) 

MOy DEFEXTt-(S.) 
. IF B CSTRNG 

CLR -(B.) 
. IFF 
.IF IDN CSTRNG. «0 

CLR -(B.) 
. IFF 

MOM CSTRNG. -(B.) 
.ENDC 
.ENDC 

EMT -Qsaa 

.ENDM 

When this programmed request is executed, all the specified arguments are 
placed on the user stack. Thus, the user stack would appear as shown in 
Figure 1-3. 

Figure 1-3: Stack Set by .CSIGEN Programmed Request 
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The EMT processor then uses these arguments in performing the function 
of the programmed request .CSIGEN. 

FORMAT 2 

The second format for programmed requests is as follows: 



.PRGREQ Area,Argl,Arg2,...,Argn 



where: 



.PRGREQ 

Area 
Argl,Arg2,...,Argn 



is the name of the programmed request 

is the address of an argument block 

are the arguments that will be contained in the 

argument block 



This format generates an EMT 375 instruction. Programmed requests that 
call the monitor via an EMT 375 use RO as a pointer to an argument block. 
In general, the argument block appears as shown in Figure 1-4. 

Figure 1-4: EMT 375 Argument Block 
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The programmed request format uses Area as a pointer to the argument 
block that contains the arguments Argl through Argn. 

.PRGREQ Area, Argl,..., Argn 

Blank fields are permitted. However, if the Area argument is empty, the 
macro assumes that RO points to a valid argument block. If any of the fields 
Argl to Argn are empty, the corresponding entries in the argument list are 
left untouched. Thus, 

.PRGREQ Area, Argl, Arg2 

points RO to the argument block at Area and fills in the first and second 
arguments, while 

.PRGREQ Area 
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points RO to the block and fills in the first word — that is, the function 
code and channel number — without filling in any other arguments. Ar- 
guments that are left blank are discussed in the following section. 

1 .1 .2.2 Blank Arguments — Any programmed request that uses an argument 
block assumes that any argument left blank has been previously loaded by 
your program into the appropriate memory location (exceptions to this are 
the .CHCOPY and .GTJB requests). For example, when the programmed 
request 

.PRGREQ Area, Argl, Arg2 

is assembled, RO will point to the first word of the argument block. The first 
word has the function code in the high-order byte and the channel number 
in the low-order byte. Argl is in the second word of the argument block 
(that is, in address RO plus 2), while Arg2 is in RO plus 4. 

There are two ways to account for arguments. You can let the MACRO 
assembler generate the instructions needed to fill up the argument block at 
run time, or you can write these instructions in your program, leaving the 
arguments in the programmed request blank for those that you have writ- 
ten in. DIGITAL recommends that you let MACRO generate the instruc- 
tions, both for program clarity and for reduced chance of programming 
error. 

The following examples are all equivalent in that the arguments have been 
accounted for either in the program instructions or in the programmed 
request. 

MDV «ARG1 .AREA+Z 
MOV i»ARGZ ,AREA + ^ 

.PRGREQ »AREA 

is equivalent to 

MOM *AREA »R0 

.PRGREQ ,«ARG1 .«ARG2 

and also to 

MOU «AREA »R0 
MOM »ARG1 .Z(RO) 
MOU «ARG2.a(R0) 



.PRGREQ 



This last example sets up all the arguments for the programmed request 
prior to executing the programmed request. 

The following example shows how arguments are specified to the .TWAIT 
programmed request. 
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.TITLE 


EXWAIT.MAC 




.MCALL 


.PRINT. .TWAIT 


START: 






WAIT: 


.TWAIT 


«EMTLST 




.PRINT 


«MSG 




BR 


WAIT 


EMTLST: 


.BYTE 


,2a 




.WORD 


TIME 


TIME: 


.WORD 


,10.*G0 


MSG: 


.ASCIZ 


/PRINT THIS E 



E^ERY TEN SECONDS/ 
.END START 

The .TWAIT programmed request suspends a program and requires two 
arguments. The first argument is area, which points to the address of a 
two-word EMT argument block; the second argument is Time, which is a 
pointer to two words of time (high-order first, low-order second) expressed 
in ticks. In the example shown above, EMTLST is specified as an argument 
with the programmed request that points to the address of the EMT argu- 
ment block. The first word of the argument block has a zero stored in the 
low-order byte representing the channel number and a function code of 24 
stored in the high-order byte. The second word contains a symbolic pointer 
to the location (the second argument), which specifies the amount of time 
that the program will be suspended. It is defined as two words and, in this 
example, represents a 10-second interval. When run, the example program 
prints its message every ten seconds. 

1.1.2.3 Addressing Modes — You must make certain that the arguments 
specified are valid source fields and that the address accurately represents 
the value desired. If the value is a constant or symbolic constant, use the 
immediate addressing mode [#]. If the value is in a register, use the regis- 
ter symbol [Rn]. If the value is in memory, use the label of the location 
whose value is the argument. 

A common error is to use n rather than #n for numeric arguments. For 
example, when a direct numerical argument is required, the immediate 
mode causes the correct value to be put into the argument block. Thus 

.PRGREQ #Area,#4 

is correct, while 

.PRGREQ #Area,4 

is not correct since the contents of location 4 are placed into the argument 
block instead of the desired value 4. 

However, the form 



DCrHDCn 



LIST: .WORD AREA 
NUMBER: .WORD a 



is correct since the contents of LIST are the argument block pointer and the 
contents of NUMBER are the data value. 
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NOTE 

All registers except RO are preserved across a programmed 
request. In certain cases, RO contains information passed 
back by the monitor; however, unless the description of a 
request indicates that a specific value is returned in RO, the 
contents of RO are unpredictable upon return from the re- 
quest. Also, with the exception of calls to the Command 
String Interpreter, the position of the stack pointer is pre- 
served across a programmed request. 

You must be sure that the selected mode generates the correct value as a 
source operand in a MOV instruction. Check the programmed request 
macro in the Macro Library (SYSMAC.SML) and expand the programmed 
request by hand or with the macro assembler (by using the .LIST MEB 
directive) to be sure of correct results. 

1.1.2.4 Keyword Macro Arguments — The RT-11 MACRO assembler sup- 
ports keyword macro arguments. All the arguments used in programmed 
request calls can be encoded in their keyword form (see the PDP-11 
MACRO-11 Language Reference Manual for details). 

In EMT 375 programmed requests, the high byte of the first word of the 
area (pointed to by RO) contains an identifying code for the request. Nor- 
mally, this byte is set if the macro invocation of the programmed request 
specifies the area argument, and it remains unaffected if the programmed 
request omits the area argument. If the macro invocation contains 
CODE = SET, the high byte of the first word of the area is always set to the 
appropriate code, whether or not area is specified. 

If CODE = NOSET is in the macro invocation, the high byte of the first 
word of area remains unaffected. This is true whether or not area is speci- 
fied. This allows you to avoid setting the code when the programmed re- 
quest is being set up. This might be done because it is known to be set 
correctly from an earlier invocation of the request using the same area, or 
because the code was statically set during the assembly process. 

1.1.2.5 Channels and Channel Numbers — A channel is a data structure that 
is a logical connection between your program and a file on a mass storage 
device or on a serial device such as the line printer or terminal. The system 
provides 16(decimal) channels by default. When a file is opened on a partic- 
ular device, a channel number is assigned to that file. The channel number 
can have an octal value from to 376 (0 to 254 decimal). Thus, your pro- 
gram first opens a channel through a programmed request by specifying 
the device and/or file name, file type, and a channel number to the monitor. 
Your program refers to that file or device in all I/O operations thereafter by 
the assigned channel number. You can specify a device (non-file-structured) 
or a device and file name (file-structured). 

Channel 255(decimal) is reserved for system use. Channel 15(decimal) is 
used by the system's overlay handler. 
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1.1.2.6 Device Blocks — A device block is a four-word block of Radix-50 
information. You set up the block to specify a physical or logical device 
name, file name, and file type for use with a programmed request. This 
information is passed to the monitor when your program opens a file. The 
monitor uses the information to locate the referenced device and the file 
name in the corresponding directory. 

For example, a device block representing the file FILE.TYP on device DK: 
could be written as 

.RAD50 /DK / 
.RAD50 /FIL/ 
.RAD50 /E / 
,RAD50 /TYP/ 

The first word contains the device name, the second and third words con- 
tain the file name, and the fourth word contains the file type. Device, file 
name, and file type must each be left-justified in the appropriate field. This 
string could also have been written as 

.RAD50 /DK FILE TYP/ 

Spaces must fill out each field. Also, the colon and period separators must 
not appear in the string since they are only used by the Command String 
Interpreter to delimit the various fields. 

If the first word of a device block is the name of a mass-storage device such 
as a disk and the second word of the block is 0, the device block refers to an 
entire volume of the mass storage device in a non-file-structured manner. 

1 .1 .2.7 Programmed Request Errors — Programmed requests use three meth- 
ods of reporting errors detected by the monitor: 

1. Setting the carry bit of the processor status word (PSW) 

2. Reporting the error code in byte 52 of the system communications area 

3. Generating a monitor error message 

If a programmed request has been executed unsuccessfully, the monitor 
returns to your program with the carry bit set. The carry bit is returned 
clear after the normal termination of a programmed request. Almost all 
requests should be followed by a Branch Carry Set (BCS) or Branch Carry 
Clear (BCC) instruction to detect a possible error. 

Because some programmed requests have several error codes — that is, 
errors can be generated for different reasons — byte 52 in the system com- 
munications area is used to receive the error code. Thus, when the carry bit 
is set, check byte 52 to find out the kind of error that occurred in the 
programmed request. The meanings of values in the error byte are de- 
scribed individually for each request. The error byte is always zero when 
the carry bit is clear. Your program should reference byte 52 with absolute 
addressing. Always address location 52 as a byte, never as a word, since 
byte 53 has a different usage. The following example shows how byte 52 
can be tested for the error code. 
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ERRBYT=52 

.PRGREO AREA »ARG1 ,. . . »ARG2 

BCB ERROR 



ERROR: TSTB @#ERRBYT 



Error messages generated by the monitor are caused by fatal errors, which 
cause your program to terminate immediately. Some fatal errors can be 
intercepted and have their values returned in byte 52 (see the 
.HERR/.SERR programmed requests). 

1.1.2.8 User Service Routine (USR) Requirement — Many programmed re- 
quests require the USR to be in memory. Some of these requests always 
require a fresh copy of the USR to be read in because the code to execute 
them resides in the USR buffer area. Since the buffer area gets overlaid by 
data used to perform other system functions, the USR must be read in from 
the system device even if there is a copy of the USR presently in memory. 
Table 1-2 shows the programmed requests that require the USR. 

Table 1-2: Programmed Requests Requiring the USR 





[uest 




Monitor 




Req 


SJ 


FB 


XM 


.CDFN 




yes* 


no 


no 


.CLOSE (see 


: Note 1) 


yes 


yes 


yes 


.CSIGEN 




yes 


yes 


yes 


.CSISPC 




yes 


yes 


yes 


.DELETE 




yes 


yes 


yes 


.DSTATUS 




yes 


yes 


yes 


.ENTER 




yes 


yes 


yes 


.EXIT 




yes 


yes 


yes 


.FETCH 




yes 


yes 


yes 


.FPRGT 




yes 


yes 


yes 


.GTLIN 




yes 


yes 


yes 


.HRESET 




yes 


no 


no 


.LOCK (see 


Note 2) 


yes 


yes 


yes 


.LOOKUP 




yes 


yes 


yes 


.QSET 




yes* 


yes* 


yes 


.RELEAS 




yes 


yes 


yes 


.RENAME 




yes 


yes 


yes 


.SFDAT 




yes 


yes 


yes 


.SRESET 




yes* 


no 


no 


.TLOCK (see Note 3) 


yes 


yes 


yes 



Note 1: Only if channel was opened with an .ENTER pro- 
grammed request 

Note 2: Only if the USR is in a swapping state 

Note 3: Only if the USR is not in use by another job 

* The requests marked with an asterisk always require a 
fresh copy of the USR to be read in before they can be 
executed. 
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USR requirements for programmed requests differ between the SJ and FB 
monitors as shown in the table. The .CLOSE programmed request on non- 
file-structured devices, such as a line printer or terminal, does not require 
the USR under any monitor. 

The USR is not reentrant and cannot be shared by concurrent jobs. Thus, 
when the USR is in use by one job, another job requiring it must queue up 
for it. This is particularly important for concurrent jobs when devices such 
as magnetic tape or cassette are active. For example, USR file operations 
on tape devices require a sequential search of the tape. When a background 
program is running the USR, the foreground job is locked out until the tape 
operation is completed. You should be aware that this operation may take 
considerable time. The .SPFUN request can be used to perform asynchro- 
nous directory operations on tape. In the FB and XM monitors, the .TLOCK 
request can be used by a job to check USR availability. 

Any request that requires the USR to be in memory can also require that a 
portion of your program be saved temporarily in the system device swap file 
(that is, "swapped out" and stored in the file SWAP.SYS to provide room for 
the USR). The USR is then read into memory. Although swapping is invisi- 
ble to you in normal operation, you must be aware of it and take some care 
in your programming. For example, the argument block being passed to the 
USR must not be in the area that is swapped over. You can optimize pro- 
grams so that they require little or no swapping, thereby saving time. 

Consider the following items if a swap operation is necessary. 

1. The background job 

If a .SETTOP request in a background job specifies an address beyond 
the point at which the USR normally resides, a swap is required when 
the USR is called. Section 2.79 details the operation of the .SETTOP 
request. This case is not encountered in XM because the USR is always 
resident. 

2. The value of location 46 

If you assemble an address into word 46 or move a value there while the 
program is running, RT— 11 uses the contents of that word as an alter- 
nate place to swap the USR. If location 46 is zero, this indicates that the 
USR will be at its normal location in high memory. If the USR does not 
require swapping, this value is ignored. 

A foreground job must always have a value in location 46 unless it is 
certain that the USR will never be swapped. If the foreground job does 
not allow space for the USR and a swap is required, a fatal error occurs. 
The SET USR NOSWAP command makes the USR permanently resi- 
dent. 

If you specify an alternate address in location 46, the SJ monitor does 
not verify the validity of the USR swap address. Thus, if the area to be 
swapped overlays the resident monitor, the system is destroyed. 

3. Monitor offset 374 

The contents of monitor offset 374 indicate the size of the USR in bytes. 
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Programs should use this information to dynamically determine the 
size of the region needed to swap the USR. 

4. Protecting program areas 

Make sure that certain areas of your program do not get overlaid when 
you swap in the USR. These areas are the program stack, any parame- 
ter block for calls to the USR, the EMT instruction that invoked the 
USR, I/O buffers, device handlers, interrupt service routines, queue 
elements, defined channels, and completion routines in use when the 
USR is being called. 

The RT—11 Software Support Manual provides additional information on 
the USR. 

1.1.3 Using Programmed Requests 

This section describes how to use and implement programmed requests to 
access the various monitor services. Chapter 2 contains, in alphabetical 
order, detailed descriptions of each request, including examples. 

1.1.3.1 Initialization and Control — Typically, you use several programmed 
requests to control the operating environment in which your program is 
running. These requests can include control of memory allocation, I/O ac- 
cess, devices, and error processing. 

MEMORY ALLOCATION 

The memory needs of a program are specified to the monitor by the .SET- 
TOP request. When loaded, a program occupies the memory specified by its 
image created at link time. To obtain more memory, a .SETTOP request is 
executed, with RO containing the highest address desired. The monitor re- 
turns the highest address available. Resident handlers or foreground jobs 
can prevent all the memory that is desired from being available to the 
program. If the memory requirements of the running program permit, the 
monitor retains the User Service Routine (USR) in memory, which reduces 
swapping. Otherwise, the monitor will automatically remove the USR from 
memory and then swap part of the user program to the swap file called 
SWAP.SYS on the system device v/henever the USR must be reloaded to 
process a request. The .SETTOP request then allows you to determine how 
much memory is available and to control monitor swapping characteristics. 
See the .SETTOP programmed request in Chapter 2 for special optional 
features provided in an extended memory environment. Additional infor- 
mation on the .SETTOP request is also given in the RT-11 Software Sup- 
port Manual. 

If a program needs so much memory that the USR must swap, swapping 
will automatically occur whenever a USR call is made. However, if a pro- 
gram knows what file operations are necessary, and if these operations can 
be consolidated and performed at one time, the efficiency of the system can 
be enhanced in the following manner: request the USR to be swapped in, 
have it remain resident while a series of consecutive USR operations is 
performed, then swap the USR out when the sequence of operations is 
completed. 
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Three programmed requests control USR swapping. The request .LOCK 
causes the USR to be made resident for a series of file operations. It can 
operate by: (1) requiring a portion of your program to be written to the 
swap blocks prior to reading in the USR; (2) only requiring a fresh copy of 
the USR if the USR buffer is overwritten; or (3) not requiring the USR to be 
read in if it finds the USR intact. The request .UNLOCK swaps your pro- 
gram back in if it was swapped out, and the USR is overwritten; otherwise, 
no swapping occurs. The request .TLOCK makes the USR resident in 
foreground/background programs, but only if the USR is not currently serv- 
icing another job's file requests at the time the .TLOCK request is issued. 
This check prevents a job from becoming blocked while the USR is process- 
ing another job's request. When a .TLOCK succeeds, the USR is ready to 
perform an operation immediately. In a single-job environment, the 
.TLOCK request performs exactly like the .LOCK request. 

RT-11 provides 16(decimal) channels as part of the job's impure 
area — that is, 16 files can be active at one time. Up to 255(decimal) 
channels can be activated with the .CDFN request. This request sets aside 
memory inside the job area to provide the storage required for the status 
information on the additional channels. Once the .CDFN request has been 
executed, as many channels as specified can be active simultaneously. Use 
the .CDFN request during the initialization phase of your program. The 
keyboard monitor command CLOSE does not work if you define new chan- 
nels with the .CDFN programmed request. 

The .CNTXSW request allows the job to add memory locations to the list of 
items to be context-switched. The request itself does not cause a context 
switch to occur. 

INPUT/OUTPUT ACCESS 

Each pending I/O, message, or timer request must be placed into one of the 
monitor queues. These are then processed by the monitor on a first-in first- 
out basis, by job priority, or by time of expiration. In RT-11, all I/O trans- 
fers are queued to allow asynchronous processing of the request. A queue is 
a list of elements, each element being seven words long (ten words [deci- 
mal] long when using the extended memory monitor). When your program 
issues a data transfer programmed request, the information specifying the 
transfer is stored by the monitor in a queue element. This information is 
passed to the device handler, which then processes the I/O transfer. 

Each job, whether background or foreground, initially has only a single 
queue element available. Additional queue elements may be set aside with 
a .QSET request. The .QSET request declares where in memory the addi- 
tional queue elements will go and how many elements there will be. If you 
do not include a .QSET request in your program, the monitor uses the 
queue element set aside in the job's impure area. In this case, since only one 
element is available for each job, all operations would be synchronous. That 
is, any request issued when the available queue element list is empty has 
to wait for that element to become free. The number of queue elements 
necessary equals the number of asynchronous operations pending at any 
time. 
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DEVICES 

The .DEVICE request turns off any special devices that are being used by 
the running program upon program termination. This request (available 
only in FB or XM) allows you to specify a set of device control register 
addresses and a value to be set in each register on job exit. When a job is 
terminated — either normally, by an error condition, or by a 
CTRL/C — the specified values are set in the specified locations. 

In SJ, a hard reset is done at .EXIT or CTRL/C. This clears all devices. 

Loading a background job with a GET, R, or RUN command, or loading a 
foreground or system job with a FRUN and SRUN command, respectively, 
alters most locations in the vector area to 476. RT-11 automatically 
prevents alteration of all locations used by the system, such as the clock, 
the console terminal, and all vectors used by handlers that are loaded. If a 
foreground job in a foreground/background environment accesses a device 
directly through an in-line interrupt service routine, the foreground job 
must notify the monitor that it must have exclusive use of the vectors. You 
use the .PROTECT programmed request to allow the foreground job to gain 
) exclusive use of a vector. The .PROTECT request can also be used by either 

the foreground or background job, prior to setting the contents of a vector, 
to test whether the vectors are already controlled by a job. This serves as 
further protection against jobs interfering with each other. An .UNPRO- 
TECT programmed request relinquishes control of a vector, making the 
vector available to both the background and foreground jobs. 

The request .SPFUN is available for performing special functions on de- 
vices such as magnetic tape. .SPFUN requests are used for such functions 
as rewind or space-forward operations. 

ERROR PROCESSING 

During the course of program execution, errors can occur that cause the 
monitor to stop the program and print a MON-F error message. Examples 
include directory I/O errors, monitor I/O errors on the system device, or I/O 
requests to nonexistent devices. Some programs cannot afford to allow the 
monitor to abort the job because of such errors. For example, in the case of 
RT-11 multi-user BASIC, a directory I/O error affecting only one of the 
users should not cause the whole program to abort. For such applications, a 
pair of requests is provided, .HERR and .SERR. A .HERR request (normal 
default) indicates that the monitor will handle severe errors and stop the 
job. A .SERR request causes the monitor to return most errors to your 
program in byte 52 for appropriate action. 

In addition to processing I/O errors through .HERR and .SERR requests, 
you can also handle certain fatal errors through the .TRPSET or .SFPA 
requests. You use these requests to prevent your program from aborting 
due to a trap to location 4 or lO(octal), or to the exception traps of the 
Floating Point Processor (FPP) or Floating Point Instruction Set (FIS). A 
.TRPSET request specifies the address of a routine that the monitor enters 
when a trap to location 4 or 10 occurs. A .SFPA request specifies the ad- 
dress of a floating-point exception routine, that is called when an exception 
trap occurs. 
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1.1.3.2 Examining System Information and Reporting Status — Several pro- 
grammed requests interrogate the system for specific details about a device 
or file that your program may be using. 

The .DATE request obtains the system date, which then can be printed on a 
report or entered as a data record in a file. The time-of-day can be obtained 
with a .GTIM request and used in the same way. A program can set the 
system date and/or time by using the .SDTTM programmed request. 
Changing the date or time has no effect on any outstanding mark time or 
timed wait requests. 

With a .GTJB request you can obtain information on whether the job is 
running in the foreground or background, the memory limits of the job, the 
virtual high limit for a job created with the linker /V option (XM only), the 
unit number of the job's console terminal (if you are using the multitermi- 
nal feature), the address of the job's channel area, the address of the job's 
impure area, and the job's logical job name (if you are using a monitor with 
the system job feature). 

Status information on a file — such as its starting block, its length, and 
the device it is located on — can be obtained with a .CSTATUS request. 
Status information on a device — such as its block length and controller- 
assignment number — can be obtained with a .DSTATUS request. 

The .MTGET and .MTSTAT programmed requests provide multiterminal 
status information when the multiterminal feature is being used. 

The programmed requests .MFPS and .MTPS read the priority bits and set 
the priority and T-bits in the processor status word (PSW). These requests 
allow a program to run without change on any processor from an LSI— 11 to 
a PDP-11/60. 

1.1.3.3 Command Interpretation — Two of the most useful programmed re- 
quests are .CSIGEN and .CSISPC. These requests call the Command String 
Interpreter (CSI), which is part of the USR. They are used to process stand- 
ard RT-11 command strings in the following general form: 

*Dev: Output/Option = Dev:Input/Option 

The asterisk is printed on the terminal by the monitor. The RT-11 system 
programs use the same command string (see the RT-11 System Utilities 
Manual). 

The .CSIGEN request analyzes the string for correct syntax, automatically 
loads the required device handlers into memory, opens the files specified in 
the command, and returns to your program with option information. Thus, 
with one request, a language processor such as the FORTRAN compiler is 
ready to input from the source files and output the listing and binary files. 
You can specify options in the command string to control the operation of 
the language processor. The .CSIGEN request uses channels through 2 to 
accommodate three output file specifications and channels 3 through 10(oc- 
tal) to accommodate six input file specifications. 
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The .CSISPC request provides you with the services of the command proces- 
sor, but allows you to do your own device and file manipulation. When you 
use .CSISPC, the CSI obtains a command string, analyzes it syntactically, 
places the results in a table, and passes the table to your program for 
appropriate action. 

The .GTLIN request obtains one line of input at a time instead of one 
character. These three requests support the indirect file function and allow 
your program to obtain one line at a time from an indirect file. Thus, if your 
program was started through an indirect file, the line is taken from the 
indirect file and not the terminal. The .GTLIN request has an optional 
argument which forces input to come from the terminal. The feature is 
useful if your program requires information which can be supplied only at 
run time. 

1.1.3.4 File Operations — A device handler is the normal RT-11 interface 
between the monitor and the peripheral device on which file operations are 
performed. The console terminal handlers (in FB and XM) and the interjob 
message handlers are part of the resident monitor and require no attention 
on your part. All other device handlers are loaded into memory with either 
a .FETCH request from the program or a LOAD command from the key- 
board before any other request can access that device. Section 1.1.3.5 of this 
manual describes the use of programmed requests for performing I/O opera- 
tions. The RT-11 Software Support Manual describes how to write device 
handlers for RT-11. 

Once the handler is in memory, a .LOOKUP request can locate existing 
files and open them for access. New files are created with an .ENTER 
request. Space for the file can be defined and allocated as: 

1. One-half the size of the largest unused space or all of the second largest 
space, whichever is larger (the default) 

2. A space of a specific size 

3. As much space as possible 

The way the system allocates the space depends upon the parameter speci- 
fied by you as the file size argument of the .ENTER request or specified in a 
.CSIGEN command string. 

When file operations are completed, a .CLOSE request makes the new file 
permanent in the directory. A .PURGE request can free the channel with- 
out making the file permanent in the directory. Existing permanent files 

request. 

Two other requests, .SAVESTATUS and .REOPEN, add to the flexibility of 
file operations. The .SAVESTATUS request stores the current status of a 
file that has been opened with a .LOOKUP request and makes the file 
temporarily inactive, thus freeing the channel for use by another file. The 
.REOPEN request causes the inactive file to be reactivated on the specified 
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channel, and I/O continues on that channel. In this manner, you can open 
more files than there are channels. If, in addition, you lock the USR in 
memory, you can open all the files your job needs while maintaining system 
swapping efficiency. The procedure is: 

1. Lock the USR in memory, and open the files that are needed. 

2. Issue the .SAVESTATUS request. 

3. Release the USR. 

4. Issue a .REOPEN request each time a file is needed. 

5. Lock USR, and use the .CLOSE request to make the files permanent. 

Because a .REOPEN request does not require any I/O, all USR swapping 
and directory motion can be isolated in the initialization code for an appli- 
cation, improving program efficiency. 

The creation date and protection status of a file can be modified by using 
the .SFDAT and .FPROT requests, respectively. 

The .SFDAT request allows you to change the date that appears in a file's 
directory entry listing. You may want to do this for a file that you update in 
place, for example, or if the original creation date was in error. 

The .FPROT request protects a file against deletion, or removes protection 
so that a file can be deleted by a .DELETE, .ENTER, or .RENAME request. 
The contents of a protected file are not protected against modification. 

1.1.3.5 Input/Output Operations — You can perform I/O in three different 
modes: 

® synchronous 
® asynchronous 
® event-driven 

These modes allow you to optimize the overlap of CPU and I/O processing. 

The programmed requests .READW and .WRITW perform synchronous 
I/O — that is, the instruction following the request is not executed until 
the I/O transfer is completely finished; thus the program and the I/O pro- 
cess are synchronized. 

The program requests .READ, .WRITE; and .WAIT perform, asynchronous 
I/O — that is, the .READ or .WRITE request adds the transfer request to 
the queue for the device; if the device is inactive, the transfer begins; con- 
trol returns to the user program before the transfer is completed. The 
.WAIT programmed request, however, blocks the program until the trans- 
fer is completed. This allows the I/O operation to be completed before any 
further processing is done. Asynchronous I/O is most commonly used for 
double buffering. 
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Program requests such as .READC and .WRITC perform event-driven 
I/O — that is, they initiate a completion routine when the transfer is fin- 
) ished. 

Event-driven I/O is practical for conditions where system throughput is 
important, where jobs are divided into overlapping processes, or where pro- 
cessing timings are random. The last condition is the most attractive case 
for using event-driven I/O because processor timing may range up to infin- 
ity in that a process is never completed. 

Since the completion routine is essential to event-driven I/O, the next sec- 
tion presents general guidelines for writing completion routines. 

COMPLETION ROUTINES 

Completion routines are part of your program. They execute following the 
completion of some external operation, interrupting the normal prograin 
flow. On entry to an I/O completion routine, Register contains the con- 
tents of the Channel Status Word and Register 1 contains the channel 
; number for the operation. The carry bit is not significant. 

Completion routines are handled differently, depending on whether the 
program is being run under the SJ monitor or the FB and XM monitors. 
Under the SJ monitor, completion routines are totally asynchronous and 
can interrupt each other. An interrupted completion routine is resumed 
when the interrupting routine is finished. Unlike completion routines run 
under FB and XM monitors, which are serialized and run at priority 0, 
completion routines run under an SJ monitor are nested. In addition, they 
execute not at priority 0, but at the same priority as the device whose 
interrupt scheduled them. For example, the completion routine resulting 
from a .WRITC programmed request to device TT: runs at priority 4. Com- 
pletion routines from timer requests run at the same priority as the system 
clock. This is particularly important on LSI-11 and PDP 11/03 systems that 
have only two interrupt levels, ON and OFF, because clock interrupts may 
be lost while lengthy completion routines execute. Under the FB and XM 
monitors, completion routines do not interrupt one another. Instead, they 
are queued, and the next routine is not entered until the first is completed. 

If the foreground job is running and a foreground I/O transfer completes 
and wants a completion routine, that routine is entered immediately if the 
foreground job is not already executing a completion routine. If it is in a 
completion routine, that routine continues to termination, at which point 
other completion routines are entered in a first-in first-out order. If the 
background job is running (even in a completion routine) and a foreground 
I/O transfer completes with a specified completion routine, execution of the 
background job is suspended and the foreground routine is entered immedi- 
ately. 

Also under the FB and XM monitors, it is possible to request a completion 
routine from an in-line interrupt service routine through a .SYNCH pro- 
grammed request. This allows the interrupt service routine to issue other 
programmed requests to the monitor. 
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Restrictions that must be observed when writing completion routines are as 
follows: 

1. Requests that require the USR must not be issued within a completion 
routine. A fatal monitor error is generated if the USR is called from a 
completion routine. 

2. Completion routines should never reside in memory space that is used 
for the USR, since the USR can be interrupted when I/O terminates and 
the completion routine is entered. If the USR has overlaid the routine, 
control passes to a random place in the USR, with a HALT or error trap 
being the likely result. 

3. Registers other than RO and Rl must be saved upon entry to completion 
routines and restored upon exiting. Registers cannot transfer data be- 
tween the mainline program and the completion routine. 

4. Under the XM monitor, completion routines must remain mapped 
while the request is active and the routine can be called. 

5. The completion routine must exit with an RTS PC instruction because 
the routine was called from the monitor with a JSR PC,ADDR, where 
ADDR is the user-supplied entry point address. If you exit completion 
routines with an .EXIT request, your job will abort. An exit from, a 
completion routine in FB or XM can be done by using an .SPCPS re- 
quest to change the mainline PC to point to an .EXIT in the main code. 
As soon as all completion routines are done, the exit will be executed. 

6. Under the XM monitor, completion routines scheduled as a result of a 
.SYNCH run in kernel mapping, not user mapping. 

Frequently, a program's completion routine needs to change the flow of 
control of the mainline code. For example, you may wish to establish a 
schedule among the various tasks of an application program after a certain 
time has elapsed, or after an I/O operation is complete. Such an application 
needs to redirect the mainline code to a scheduling subroutine when the 
application's timer or read/write completion routine runs. The .SPCPS pro- 
grammed request, which can only be used in a foreground/background or 
extended memory environment, saves the mainline code program counter 
and processor status word, and changes the mainline code program counter 
to a new value. If the mainline code is performing a monitor request, that 
request finishes before rerouting can occur. 

TERMINAL INPUT/OUTPUT 

Several programmed requests are available to provide an I/O capability 
with the console terminal: a .TTYIN request obtains a character from the 
console; a .TTYOUT request prints a character on the terminal; long 
strings of characters — even multiple lines — are output with the 
.PRINT request. Programs can also issue .TTINR and .TTOUTR requests, 
which indicate that a character is not available or that the output buffer is 
full. The program can then resume operation and try again at a later time. 
A .RCTRLO request forces the terminal output to be reactivated after a 
CTRL/0 has been typed to suppress it, so that urgent messages will be 
printed. 
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You can use the .TTYIN/.TTINR requests in special (single-character) 
mode by setting bit 12 of the Job Status Word. See the .TTYIN programmed 
request for a description of special mode. 

MULTITERMINAL REQUESTS 

The RT-11 multiterminal feature allows your program to perform 
input/output on up to 17 terminals. Several programmed requests allow 
you to perform I/O on these terminals. Before issuing any of these pro- 
grammed requests to a terminal, you must issue the .MTATCH request, 
which reserves the specified terminal for exclusive use by your program. 
The terminal cannot then be used by any other job until you issue the 
.MTDTCH request to detach the terminal. 

The .MTIN request returns to a program characters that are typed at the 
terminal, while the .MTOUT and .MTPRNT requests send characters to a 
terminal. These requests are analogous to the .TTYIN, .TTYOUT, and 
.PRINT requests. Note that the .TTYIN/.TTINR, .TTYOUT/.TTOUTR, and 
.PRINT requests can only be used with the console terminal. 

You can set terminal and line characteristics with the .MTSET request. 
You provide a four-word status block that contains the terminal status 
word, the character of the terminal requiring fillers and the number of 
fillers required for this character, the width of the carriage (80 characters 
by default), and system terminal status. The status of a terminal can be 
obtained by issuing the .MTGET request. The .MTSTAT request provides 
multiterminal system status information. 

1.1.3.6 Foreground/Background Communications — ■ Communication between 
foreground and background jobs is obtained through the programmed re- 
quests .SDAT and .RCVD. These requests also have three modes (synchro- 
nous, asynchronous, and event driven) that allow transfer of buffers be- 
tween the two jobs as if I/O were being done. The sending job treats a 
.SDAT request as a write, and the receiving job treats .RCVD as a read. In 
the case of .RCVD requests, the receiving buffer must be one word longer 
than the number of words expected. When the data transfer is completed, 
the first y/ord of the buffer contains the number of words actually sent. 

Jobs receiving messages can be activated when messages are sent through 
.RCVDC completion routines, while the sending jobs use .SDATC comple- 
tion routines. The .MWAIT request is used for synchronizing message re- 
quests. It is similar to the .WAIT request that is used for normal I/O. 

If you want one job in a foreground/background environment to read or 
write data in a file opened by the other job, use the .CHCOPY request. For 
example, when the background job is processing data that is being collected 
by the foreground job, the .CHCOPY request allows you to obtain channel 
information from the foreground job and to use that channel information to 
control a read or write request. 

The foreground/background monitor always causes a context switch of criti- 
cal items such as machine registers, the job status area, and floating-point 
processor registers when a different job is scheduled to run because it has a 
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higher priority, or because the current job is blocked and a lower priority 
job is runnable. When the monitor saves a job's context, it saves the job- 
dependent information on the job's stack so that this information can be 
restored when the job is runnable again. 

1.1.3.7 Timer Support — Timer support by the monitor is provided through 
the .MRKT request. With the .MRKT request, you specify the address of a 
routine that is to be entered after a specified number of clock ticks. Like I/O 
completion routines, .MRKT routines are asynchronous and independent of 
the main program. After the specified time elapses, the main program is 
interrupted, the timer completion routine executes, and control returns to 
the interrupted program. 

Pending .MRKT requests — as many as the queue can hold — are identi- 
fied by number. Pending timer requests can be canceled with a .CMKT 
request. .MRKT requests are normally used as a scheduling tool where jobs 
are scheduled on the basis of clock events, detected by timer completion 
routines. 

The programmed requests .MRKT/.CMKT and .TIMIO/.CTIMIO require re- 
quest identification words as an argument. Certain ranges of values are 
reserved for different uses as shown in the following table. 

Range Use 

1-176777 For user applications with .MRKT/.CMKT. Values in 

this range are canceled if a .CMKT request is issued 
with a value of 0. 

177000-177377 For use in device handler .TIMIO/.CTIMIO requests. 
To ensure a unique value for each handler, DIGITAL 
suggests that the value be assigned as 
177000 + devcod, where devcod represents the device 
identifier value used in the .DRDEF macro at the 
beginning of the handler. 

177400-177477 Reserved for multiterminal support. 

177500-177677 Reserved. 

177700 Used by the .TWAIT request. 

177701-177766 Reserved. 

177767-177777 DECnet. 

Values in the range 177000 to 177677 must be canceled individually by the 
rouLine mat issuea tne .iiiviiw request, inis wouia occur, tor example, in 
handler abort code. 

Values in the range 177700 to 177777 are automatically canceled whenever 
a program terminates or aborts. 

A job can be suspended for a specified time interval with a .TWAIT request. 
For example, the .TWAIT request will allow a compute-bound job to relin- 
quish CPU time to the rest of the system, permitting other jobs to run. 
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1.1.3.8 Program Termination or Suspension — Many jobs come to an execu- 
tion point where there is no further processing necessary until an external 
event occurs. In the FB or XM environment such a job can issue a .SPND 
request to suspend the execution of that job. While the foreground job is 
suspended, the background job runs. When the desired external event oc- 
curs, it is detected by a previously requested completion routine, which 
executes a .RSUM request to continue the job at the point where it was 
suspended. 

When a job is ready to terminate or reaches a serious error condition, it can 
reset the system with the .SRESET and .HRESET requests. .SRESET is a 
soft reset. That is, the monitor data base for the job is reinitialized, but 
queued I/O is allowed to run to completion. .HRESET is a hard reset where 
all I/O for the job is stopped (by a RESET instruction in the SJ monitor or 
by calls to the handlers in an FB environment). 

Use the programmed request .EXIT in a background job to return control to 
the keyboard monitor by causing program termination. If Register con- 
tains a zero upon execution of this request, a hard reset is performed, and 
the commands REENTER, CLOSE, and START are disabled. If Register 
contains a non-zero value upon exit from your program, a soft reset is done, 
and these commands are not disabled. In a foreground job, an .EXIT pro- 
grammed request stops the job but does not return control to the keyboard 
monitor. The job can be removed from memory by the UNLOAD command. 

You may initiate the execution of another program with a .CHAIN request 
from a background job. Files remain open across a .CHAIN request and 
data is passed in memory to the chained job, so that it can adjust process- 
ing. In FORTRAN, channel information is stored in the job's impure area, 
and this information is not preserved across a .CHAIN request. Thus, close 
any channels in the first program, and reopen them in the program being 
chained to. 

1.1.3.9 System Job Communications — System job support allows communi- 
cations between any two jobs in the system. The background job, designated 
by the logical job name 'B', and the foreground job, designated by the logi- 
cal job name 'F', can send and receive messages between each other by 
using the .RCVD and .SDAT programmed requests. 

All jobs (that is, background, foreground, and system jobs) can communi- 
cate with each other by using the Message Handler (MQ). The MQ handler 
performs like an ordinary RT-11 device handler in the way it accepts and 
dispatches I/O requests from the queued I/O system. This permits .READ 
and . w^RITE requests to send messages between any two jobs as if they 
were data transfers to files. Both the sending and receiving job must issue a 
.LOOKUP request on a channel and use 'MQ' as the device specification 
and the logical job name of the job with which they are communicating as 
the file specification. In the case of .READ requests, the receiving buffer 
must be one word longer than the number of words expected. When the 
data transfer is completed, the first word of the buffer contains the number 
of words actually sent (identical to the .RCVD requests). This does not 
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apply to the .WRITE requests; the first word of the sending buffer is the 
first word of the message to be sent. Note that the Message Handler (MQ) 
can also be used under the distributed FB monitor; it does not require the 
system job special feature. 

Care should be taken when assigning logical job names to system jobs. 
Programmed requests such as .LOOKUP, .CHCOPY, and .GTJB must use 
the job's current logical job name (see the RT-11 System User's Guide). 

1.1.3.10 Extended Memory Functions — The RT-11 extended memory (XM) 
monitor permits MACRO programs to access extended memory by mapping 
their virtual addresses to physical locations in memory. This is done in 
conjunction with a hardware option called the Memory Management Unit 
that converts a 16-bit virtual address to an 18- or 22-bit physical address. 

You access extended memory in a program through programmed requests. 
In accessing extended memory, you must first establish window and region 
definition blocks. Next, you must specify the amount of physical memory 
the program requires and describe the virtual addresses you plan to use. Do 
this by creating regions and windows. Then, associate virtual addresses 
with physical locations by mapping the windows to the regions. You can 
remap a window to another region or part of a region, or you can eliminate 
a window or a region. Once the initial data structures are set up, you can 
manipulate the mapping of windows to regions that best meet your require- 
ments. 

There are four types of extended memory programmed requests: 

1. Window requests 3. Map requests 

2. Region requests 4. Status requests 

The window and region requests have their own data structures. RT-11 
provides the macro .WDBBK to create a window definition block and the 
macro .RDBBK to create a region definition block. Both macros automati- 
cally define offsets and bit names. Two other macros, .WDBDF and 
.RDBDF, define only the offsets and bit names. 

The programmed request .CRAW is used to create a window. To eliminate a 
window, use the .ELAW request. A region is created using the .CRRG 
request. You return a region to the free list of memory with the .ELRG 
request. 

You map a window to a region with the .MAP request. If a window is 
already mapped to a region, this window is unmapped and the new one is 
mapped. Use the .UNMAP request to unmap a window. You obtain the 
mapping status of a window with the .GMCX request. 

Certain programmed requests are restricted when they are in an extended 
memory environment. These programmed requests and their restrictions 
are as follows: 

.CDFN All channels must be in the lower 28K of memory (but 

not in the PARI region, 20000-37776 octal). 
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.QSET All queue elements must be lO(decimal) words long and 

in the lower 28K of memory (but not in the PARI re- 
gion, 20000-37776 octal). 

.SETTOP Effective only in the virtual address space that is 
mapped at the time the request is issued, unless the job 
was linked with the A^ option (see the RT-11 System 
Utilities Manual). 

.CNTXSW Not usable in virtual jobs. 

Detailed information on programmed requests in an extended memory en- 
vironment is given in the RT-11 Software Support Manual. 

1.1.3.11 Interrupt Service Routines — The system macro library 
(SYSMAC.SML) contains some macros that are not programmed requests, 
but are used like programmed requests in interrupt service communication 
to the monitor. The first macro call in every interrupt routine is .INTEN, 
which causes the system to use the system stack for interrupt service and 
allows the monitor scheduler to make note of the interrupt. If device service 
is all the routine does, .INTEN is the only call it need make. If you need to 
issue one or more programmed requests, such as .READ or .WRITE from 
the interrupt service routine, you must issue the .SYNCH call. The .INTEN 
call described above switches execution to the system state, and since pro- 
grammed requests can only be made in the user state, the .SYNCH call 
handles the switch back to the user state. The code following the .SYNCH 
call executes as a completion routine. When the .SYNCH is finished, the 
completion routine can execute programmed requests, initiate I/O, and re- 
sume the mainline code. The first word after the .SYNCH call is the return 
address on error, while the second word is the return on success. The 
RT-11 Software Support Manual contains a detailed description of inter- 
rupt service routines. 

1.1.3.12 Device Handiers — The system macro library (SYSMAC.SML) con- 
tains several macros that simplify the writing of a device handler. A device 
handler is divided into several sections. These sections are as follows: 

® Preamble section ® Interrupt service section 

® Header section ® I/O completion section 

® I/O initiation section ® Termination section 

The .DRDEF macro is used near the beginning of your device handler, and 

r 1- _ri.l-_ 1- ;_ 4-l._ Ul„ 4.;«_ TTU^ TkTDTJTT'O. ».^«^».« 

ptsriui'iiiB iiiui;xi vi wic "wuii^. in mc picaiiiuic iscwtujii. xiic .j_^ivjjijvjr ii.i.a\^i.\j 

sets up the first five words in the header section, stores information in 
block of the handler file, and creates some global symbols. The .DRAST 
macro sets up the interrupt entry point and the abort entry point in the 
interrupt service section, and lowers the processor priority. The .DRFIN 
macro generates the instructions for the jump back to the monitor at the 
end of the handler I/O completion routine. The .DREND macro generates 
handler termination code. The .DRBOT macro sets up the primary driver. 
A primary driver must be added to a standard handler for a data device to 
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create a system device handler. The .DRINS macro sets up the install code 
area by generating the CSR words used by INSTALL and RESORC. The 
.DRSET macro sets up the option table for the SET command in block of 
the device handler file. The .DRVTB macro sets up a table of vectors for 
devices that require more than one vector. 

Each of the device handler macros is described in Chapter 2. The RT-11 
Software Support Manual details the use of these macros in writing a de- 
vice handler. 

1.1.4 Compatibility With Previous RT-11 Versions 

Programmed requests were implemented differently in each major release 
of RT-11. The following sections outline the changes that were made to the 
programmed requests from version to version. 

1.1.4.1 Version 1 Programmed Requests — Programmed requests provided 
with the first release of RT-ll, such as .READ and .WRITE, were designed 
for a single-user, single-job environment. As such, they differ significantly 
from the programmed requests of the later versions. For Version 1 requests, 
arguments were pushed on the stack instead of being stored, as they are 
presently, in an argument block. The channel number was limited to the 
range through 17(octal), while later versions can allocate an additional 
number of channels. Also, no arguments could be omitted in the macro call. 

Programs written for use under Version 1 assemble and execute properly 
under Versions 3, 4, and 5 when the ..VI.. macro call is used. The ..VI.. 
macro call causes all Version 1 programmed requests to expand exactly as 
they did in Version 1. The ..V2.. macro call expands all requests in Version 
2 format. However, it is to your advantage to convert Version 1 and Version 
2 programs to the current format for programmed requests (see Section 
2.7). Future versions of RT-11 may no longer support the older formats. 

1.1.4.2 Version 2 Programmed Requests — The release of RT-11 Version 2 
included new programmed requests and a different way of handling argu- 
ments. The new programmed requests reflected RT-ll's ability to run a 
foreground job as well as a background job. They included requests to 
suspend/resume the foreground job and to share messages and data be- 
tween the two jobs. 

Arguments in Version 2 programmed requests were stored in an argument 
block instead of on the stack. Another difference in Version 2 was that 
arguments could be omitted from macro calls. If the Area 
argument — that is, the pointer to the argument block — was omitted, 
the macro assumed that RO pointed to a valid argument block. If any of the 
optional arguments were not present, the macro placed a zero in the argu- 
ment block for the corresponding argument. Version 1 programmed re- 
quests were modified to incorporate these changes, and the ..VI.. macro was 
provided to allow Version 1 programmed requests to execute under Version 
2 without further modification. 
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Programs written for use under Version 2 assemble and execute properly 
under Versions 3 and 4 when the ..V2.. macro call is used. The ..V2.. macro 
call causes all programmed requests prior to Version 3 to expand in Version 
2 format. 

1.1.4.3 Version 3 Programmed Requests — The programmed requests for 
Version 3 provide means for user programs to access regions in extended 
memory and to use more than one terminal. The chief difference between 
Version 2 and Version 3 programmed requests is the way in which omitted 
arguments are handled. In Versions 3, 4, and 5, blank arguments in the 
macro calls do not cause zeros to be entered into the argument block, but 
leave the corresponding argument block entry for the missing argument 
untouched. 

This change can have a significant impact on user programs. If an argu- 
ment block within a program is to be used many times for similar calls, you 
can save instructions by setting up the argument block entries only once (at 
assembly or run time), and leaving the corresponding fields blank in the 
macro call. 

However, you should keep in mind that you may not substitute zeroes for 
missing fields. Programs written with this assumption operate incorrectly 
and exhibit a wide range of symptoms that can be hard to diagnose. There- 
fore, you must write the necessary instructions to fill the argument block if 
a programmed request is issued with fields left blank in the argument list. 

Programmed requests from previous versions were modified to incorporate 
this change, and the ..V2.. macro call was provided so that Version 2 pro- 
grams could execute properly under Version 3 without further modifica- 
tion. 

1.1.4.4 Version 4 Programmed Requests — Certain programmed requests 
have taken on additional functions to support the system job feature. These 
programmed requests and their additional functions follow: 

Programmied Request Added Function 

.GTJB Returns logical job name. 

.CHCOPY May specify logical job name. 

.LOOKUP Opens message channel to any job; issues 

.READ/C/W, .WRITE/C/W, and .WAIT re- 
quests to communicate between jobs. 

programmed requests and modified others. The requests added for Version 
5 are .ABTIO, .FPROT, .PEEK, .POKE, .PVAL, and .SFDAT. Although the 
XM monitor was expanded to support 22-bit Q-bus addressing, from a pro- 
gram's point of view the extended memory programmed requests are un- 
changed from Version 4. Channel number 377 is now reserved for system 
use and is always unavailable to user programs. The programmed requests 
which have changed between Version 4 and Version 5 are summarized 
below: 
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Programmed Request Added Function 

.CSTAT Available under SJ monitor. 

.TWAIT Available under SJ monitor. 

.FETCH Available under XM monitor. 

.GTLIN Optional argument to force terminal in- 

put. 

1.1.5 Programmed Request Conversion 

The previous sections describe the modified format of programmed requests 
that were developed after those of Version 1. This section describes the 
conversion process from the Version 1 format to Version 3. 

1 .1 .5.1 Macro Calls Not Requiring Conversion — Version 1 macro calls that do 
not require any conversion are as follows: 



CSIGEN 


.LOCK 


.SRESET 


CSISPC 


.PRINT 


.TTINR (Note 2) 


DATE 


.QSET 


.TTOUTR (Note 2) 


DSTATUS 


.RCTRLO 


.TTYIN 


EXIT 


.RELEAS 


.TTYOUT 


FETCH 


.SETTOP (Note 1) 


.UNLOCK 


HRESET 







Note 1: Provided that location 50 is examined for the maximum value. 
Note 2: Except in FB or XM systems. 

1.1.5.2 ft^acro Calls That Can Be Converted — Version 1 macro calls that can 
be converted are as follows: 



CLOSE 


.RENAME 


DELETE 


.REOPEN 


ENTER 


.SAVESTATUS 


LOOKUP 


.WAIT 


READ 


.WRITE 



The general format of the ..VI.. system macro is 

.PRGREQ Chan,Argl,...,Argn 

In this form, Chan is an integer between and 17 (octal) and is not a 
general assembler argument. The channel number is assembled into the 
EMT instruction itself. The arguments Arel thrnue-h Anrn are pit.hpr 
moved into RO or pushed on the stack. 

The ..V2.. equivalent of the above call is 

.PRGREQ Area,Chan,Argl,...,Argn 

In this form, the Chan argument can be any legal assembler argument and 
can be in the range from to 377(octal). Area points to an argument block 
where the arguments Argl through Argn will be placed. 
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For example, consider a .READ programmed request in both forms: 

Version 1: .READ 5 .«BUFF ,#25G. tBLDCK 
Version 2: .READ #AREA >«5 .«BUFF »#Z5G. »BLOCK 



AREA: .WDRDO ! CHANNEL/FUNCT ION CODE HERE 
WORD iBLOCK NUMBER HERE 
WORD iBUFFER ADDRESS HERE 
WORD iWORD COUNT HERE 
WORD ;A 1 GOES HERE 

Thus, the difference in the two macro calls is that Version 2 declares the 
channel number as a legal assembler argument and adds an Area argu- 
ment. 

Table 1-3 shows a complete list of conversions for the programmed requests 
that can be converted. Version 1 and Version 2 formats are given. In Ver- 
sions 3 and later, this function is performed automatically. The arguments 
shown inside the square brackets ([ ]) are optional. Refer to the appropriate 
section in Chapter 2 for more details on each request. 

Table 1-3: Programmed Request Conversions (Version 1 to 
Version 2) 



Version 


Programmed Request 


VI: 
V2: 


.DELETE chan,dblk 

.DELETE area,chan,dblk[,count] 


VI: 
V2: 


.LOOKUP chan,dblk 
.LOOKUP area,chan,dblk[,count] 


VI: 
V2: 


.ENTER chan,dblk[,length] 

.ENTER area,chan,dblk[,length[,count]] 


VI: 
V2: 


.RENAME chan.dblk 
.RENAME area,chan,dblk 


VI: 
V2: 


.SAVESTAT chan,cblk 
.SAVESTAT area,chan,cblk 


VI: 
V2: 


.REOPEN chan.cblk 
.REOPEN area,chan,cblk 


VI: 


.CLOSE chan 


V2: 


.CLOSE chan 


VI: 
V2: 


•READ/.READW chan.buff.wcnt.blk 

RP.An/ RF.ADW nr-oa rhan Vinff w^-nt V.1L- 


VI: 
V2: 


.READC chan,buff,wcnt,crtn,blk 
.READC area,chan,buff,wcnt,crtn,blk 


VI: 
V2: 


.WRITE/. WRITW chan,buff,wcnt,blk 
.WRITE/. WRITWarea,chan,buff,wciit,blk 


VI: 
V2: 


.WRITC chan,bufr,wcnt,crtn,blk 
.WRITC area,chan,buff,wcnt,crtn,blk 


VI: 


.WAIT chan 


V2: 


.WAIT chan 
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Several important features of Version 3 calls to be kept in mind when using 
them are as follows: 

1. Version 3 calls require the area argument, which points to the area 
where the other arguments will be (unless RO already points to it and 
the first word is set up). 

2. Enough memory space must be allocated to hold all the required argu- 
ments. 

3. The chan argument must be a legal assembler argument, not just an 
integer between and 17(octal). 

4. Blank fields are permitted in the Version 3 calls. Any field not specified 
(left blank) is not modified in the argument block. 

1.1.6 Programmed Request Summary 

Many programmed requests operate only in a specific RT-11 environment, 
such as under a foreground/background monitor or when using a special 
feature such as multiterminal operation. Table 1-4 lists the programmed 
requests that can be used in all RT-11 environments, including multiter- 
minal operation. Table 1-5 lists the additional programmed requests that 
can be used under the foreground/background monitor and extended mem- 
ory monitor. The EMT and function code for each request are shown in 
octal. Although only the first six characters of the programmed request are 
significant to the Macro assembler, the longer forms are shown to provide a 
better understanding of the request function. Also, the purpose of each 
request is described. 

Macros that are used in interrupt service routines and in writing device 
handlers are listed since they are a part of the system maccro library. 

Table 1^ summarizes the programmed requests that work in all RT-11 
environments. The programmed requests followed by (MT) work only under 
the multiterminal feature of RT-11. 

Table 1—4: Programmed Requests for All RT— 11 Environments 



Name 



EMT Code 



Purpose 



.ABTIO 
.ADDR 

.ASSUME 

.BR 

.CDFN 
.CHAIN 



374 13 Aborts I/O in progress on the specified channel 

— — Computes a specified address in a position-inde- 

pendent manner 

— — Tests for a specified condition; if test is false, gen- 

erates assembly error and prints descriptive mes- 
sage 

— — Warns if code which belongs together is separated 

during assembly 

375 15 Defines additional channels for I/O 

374 10 Chains to another program (in background job 

only) 



(continued on next page) 
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Table 1-4: Programmed Requests for All RT-11 Environments 

(Cont.) 



Name 



.DRINS 

.DRSET 
.DRVTB 



.FETCH 



EMT Code 



Purpose 



.CLOSE 


374 


6 


.CMKT 


375 


23 


.CSIGEN 


344 


— 


.CSISPC 


345 


— 


.CSTAT 


375 


27 


.CTIMIO 


— 


— 


.DATE 


374 


12 


.DELETE 


375 





•DRAST 


— 


— 


.DRBEG 


— 


— 


.DRBOT 


— 


— 


.DRDEF 


— 


— 


.DREND 


— 


— 


DRFIN 







DSTATUS 


342 


ENTER 


375 


EXIT 


350 



343 — 



Closes the specified channel 

Cancels an unexpired mark time request (special 
feature in single-job environment) 

Calls the Command String Interpreter (CSI) in 
general mode 

Calls the Command String Interpreter (CSI) in 
the special mode 

Returns the status of the specified channel 

Used within a device handler as a macro call to 
cancel a mark time request (special feature) 

Moves the current date information into RO 

Deletes the file from the specified device 

Used with device handlers to create the asynchro- 
nous entry points to the handler 

Used with device handlers to create a five-word 
header, and .ASECT locations 52 through 60 

Used with system device handlers to set up the 
primary driver 

Used with device handlers to set up handler 
parameters, call driver macros from the library, 
and define useful symbols 

Used with device handlers to generate the table of 
pointers into the resident monitor 

Used with device handlers to generate the code 
required to exit to the completion code in the resi- 
dent monitor 

Sets up installation code area in block of a de- 
vice handler, and defines system and data device 
installation entry points 

Used with device handlers to create the list of SET 
options for a device 

Used with multivector device handlers to generate 
a table that contains the vector location, interrupt 
entry point, and processor status word for each de- 



Returns the status of a particular device 

Creates a new file for output 

Exits the user program and optionally passes a 
command to KMON 

Loads a device handler into memory 



(continued on next page) 
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Table 1-4: Programmed Requests for All RT-11 Environments 
(Cont.) 



Name 



EMT Code 



Purpose 



•FORK 



FPROT 


375 


43 


.GTIM 


375 


21 


,GTJB 


375 


20 


.GTLIN 


345 


— 


.GVAL 


375 


34 


.HERR 


374 


5 


.HRESET 


357 






.INTEN 



.LOCK 



346 — 



.LOOKUP 


375 


1 


.MFPS 


— 


— 


.MRKT 


375 


22 


.MTATCH (MT) 


375 


37 


.MTDTCH (MT) 


375 


37 


.MTGET (MT) 


375 


37 


.MTIN (MT) 


375 


37 


.MTOUT (MT) 


375 


37 


.MTPRNT (MT) 


375 


37 



Generates a subroutine call in an interrupt ser- 
vice routine that permits long but not critical pro- 
cessing to be postponed until all other interrupts 
are dismissed 

Sets or removes a file's protection 

Gets the time of day 

Gets parameters of a job 

Accepts an input line from either an indirect com- 
mand file or the console terminal 

Returns contents of a monitor fixed offset 

Specifies termination of a job on fatal errors 

Terminates I/O transfers and does a .SRESET op- 
eration 

Generates a subroutine call to notify the monitor 
that an interrupt has occurred, requests system 
state, and sets processor priority to the specified 
value 

Makes the monitor User Service Routine (USR) 
permanently resident until an .EXIT or .UN- 
LOCK is executed; the user program is swapped 
out, if necessary 

Opens an existing file for input and/or output via 
the specified channel; opens a message channel to 
a specified job 

Reads the priority bits in the processor status 
word, but does not read the condition codes 

Marks time, that is, sets an asynchronous routine 
to be entered after specified interval (special fea- 
ture in single-job environment) 

Attaches a terminal for exclusive use by the re- 
questing job 

Detaches a terminal from one job and frees it for 
use by other jobs 

Returns the status of a specified terminal to the 
user 

Operates as a .TTYIN request for a multiterminal 
configuration 

Operates as a .TTYOUT request for a multitermi- 
nal configuration 

Operates as a .PRINT request for a multiterminal 
configuration 



(continued on next page) 
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Table 1-4: Programmed Requests for All RT-11 Environments 
(Cont.) 



Name 



EMT Code 



Purpose 



.MTPS 


— 


— 


.MTRCTO (MT) 


375 


37 


.MTSET (MT) 


375 


37 


.MTSTAT (MT) 


375 


37 


PEEK 


375 


34 


POKE 


375 


34 


PRINT 


351 


— 


PURGE 


374 


3 


PVAL 


375 


34 


QELDF 






.QSET 


353 


— 


RCTRLO 


355 






.READ 



.READC 



375 



375 



READW 


375 


RELEASE 


343 


RENAME 


375 



10 



10 



10 



REOPEN 


375 


6 


.SAVESTATUS 


375 


5 


.SCCA 


375 


35 



Sets the priority bits, condition codes, and T-bit in 
the processor status word 

Resets the CTRL/0 flag for the designated termi- 
nal 

Modifies terminal status in a multiterminal con- 
figuration 

Provides multiterminal system status 

Examines memory locations 

Changes memory locations 

Outputs an ASCII string terminated by a zero 
byte or a 200 byte 

Clears out a channel for reuse 

Replaces contents of a monitor fixed offset 

Used with device handlers to define offsets in the 
I/O queue element 

Increases the size of the monitor I/O queue 

Enables output to the terminal, overriding any 
previous CTRL/0 

Transfers data on the specified channel to a mem- 
ory buffer and returns control to the user program 
when the transfer request is entered in the I/O 
queue; no special action is taken upon completion 
of I/O 

Transfers data on the specified channel to a mem- 
ory buffer and returns control to the user program 
when the transfer request is entered in the I/O 
queue; upon completion of the read, control trans- 
fers asynchronously to the completion routine 
specified in the .READC request 

Transfers data via the specified channel to a mem- 
ory buffer and returns control to the user program 
only after the transfer is complete 



— Removes a device handler from memory 



Changes the name of the indicated file to a new 

magtape, the handler returns an invalid operation 
code 

Restores the parameters stored via a .SAVE- 
STATUS request and reopens the channel for I/O 

Saves the status parameters of an open file in user 
memory and frees the channel for use 

Enables intercept of CTRL/C commands 



(continued on next page) 
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Table 1-4: Programmed Requests for All RT-11 Environments 
(Cont.) 



Name 



.SDTTM 
.SERR 

.SETTOP 



.TIMIO 



.TLOCK 



EMT Code 



Purpose 



.SFDAT 


375 


42 


.SFPA 


375 


30 


SOB 


— 


— 


.SPFUN 


375 


32 


.SRESET 


352 


— 


.SYNCH 


_ 






•TRPSET 


375 


3 


.'ITINR 


340 





.TTYIN 






.TTYOUT 


341 


— 


.TTOUTR 






.TWAIT 


375 


24 


.UNLOCK 


347 


— 


..VI.. 


— 


— 


..V2.. 


— 


— 


.WAIT 


374 





.WRITC 


375 


11 



375 40 Sets the system date and/or time 

374 4 Inhibits most fatal errors from aborting the cur- 

rent job 

354 — Specifies the highest memory location to be used 

by the user program 

Changes a file creation date in a directory entry 

Sets user interrupt for floating-point processor ex- 
ceptions 

Simulates the SOB instruction 

Performs special functions on magtape, cassette, 
diskette, and some disk devices 

Resets all channels and releases the device han- 
dlers from memory 

Generates a subroutine call that enables your pro- 
gram to perform programmed requests from 
within an interrupt service routine 

— — Grenerates a subroutine call in a handler to sched- 

ule a mark time request (special feature in all en- 
vironments) 

374 7 Indicates if the USR is currently used by another 

job and performs exactly as a .LOCK request in a 
single-job environment 

Sets a user intercept for traps to monitor locations 
4 and 10 

— Reads one character from the keyboard buffer 

Transfers one character to the terminal input 
buffer 

Suspends the running job for a specified amount of 
time 

Releases the USR after execution of a .LOCK and 
swaps in the user program, if required 

Provides compatibility with Version 1 format 

Provides compatibility with Version 2 format 

Waits for completion of all I/O on a specified chan- 
nel 

Transfers data on the specified channel to a device 
and returns control to the user program when the 
transfer request is entered in the I/O queue; upon 
completion of the write, control transfers asyn- 
chronously to the completion routine specified in 
the .WRITC request 



(continued on next page) 
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Table 1-4: Programmed Requests for All RT-11 Environments 
(Cont.) 



Name 



EMT Code 



Purpose 



.WRITE 



.WRITW 



375 11 Transfers data on the specified channel to a device 

and returns control to the user program when the 
transfer request is entered in the I/O queue; no 
special action is taken upon completion of the I/O 

375 11 Transfers data on the specified channel to a device 

and returns control to the user program only after 
the transfer is complete 



Table 1-5 lists the additional programmed requests that can be used only 
in a foreground/background and extended memory environment. The pro- 
grammed requests followed by (XM) operate only in an extended memory 
environment. 

Table 1-5: Foreground/Background and Extended Memory 
Programmed Requests 



Name 



EMT Code 



Purpose 



Allows one job to access another job's channel 

Requests that the indicated memory locations be 
part of FB or XM context switch process 

Creates a window in virtual memory 

Creates a region in extended memory 

Allows device interrupts in FB or XM to be disa- 
bled upon program termination 

Eliminates an address window in virtual memory 

Eliminates an allocated region in extended mem- 
ory 
Returns mapping status of a specified window 

Maps a virtual address window to extended mem- 
ory 

Waits for messages to be processed 

Requests that specified vectors in the area from 
to 476 be given exclusively to the cun-ent job 

Receives data — allows a job to read messages or 
data sent by another job in an FB environment. 
The three modes correspond to the .READ, 
.RE ADC, and .READW requests 

Reserves space in a program for a region defini- 
tion block and sets up the region size and region 
status word 

Defines the offsets and bit names associated with 
a region definition block 

(continued on next page) 



.CHCOPY 


375 


13 1 


.CNTXSW 


375 


33 ] 
1 


.CRAW (XM) 


375 


36 ( 


.CRRG (XM) 


375 


36 < 


.DEVICE 


375 


14 

1 


.ELAW (XM) 


375 


36 


.ELRG (XM) 


375 


36 

( 


.GMCX (XM) 


375 


36 


.MAP (XM) 


375 


36 


.MWAIT 


374 


' 11 


.PROTECT 


375 


31 


.RCVD 


375 


26 


.RCVDC 






.RCVDW 






.RDBBK (XM) 


— 


— 


.RDBDF (XM) 


— 


— 
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Table 1-5: Foreground/Background and Extended Memory 
Programmed Requests (Cont.) 



Name EMT Code Purpose 



.RSUM 374 2 Causes the mainline code of the job to be resumed 

after it was suspended by a .SPND request 

Sends messages or data to the other job in an FB 
environment. The three modes correspond to the 
.WRITE, .WRITC, and .WRITW requests 

Used in a completion routine to change the flow of 
control of the mainline code (special feature) 

Causes the running job to be suspended 

Unmaps a virtual address memory window 

Cancels the .PROTECT vector protection request 

Reserves space in a program for a window defini- 
tion block and sets up the associated data 

Defines the offsets and bit names associated with 
a window definition block 



.SDAT 


375 


25 


.SDATC 






.SDATW 






.SPCPS 


375 


41 


.SPND 


374 


1 


.UNMAP (XM) 


375 


36 


.UNPROTECT 


375 


31 


.WDBBK (XM) 


— 


— 


.WDBDF (XM) 







1 .2 Using the System Subroutine Library 

The system subroutine library is a collection of FORTRAN-callable 
routines that allow various RT-11 system features to be used by a FOR- 
TRAN programmer. There are no FORTRAN routines in SYSLIB to access 
extended memory under the extended memory (XM) monitor. 

This collection of subroutines is placed in a system library called SYS- 
LIB.OBJ. This library file also contains the overlay handlers, utility func- 
tions, a character string manipulation package, and two-word integer sup- 
port routines. The linker uses this library to resolve undefined globals. It is 
resident on the system device (SY:). 

You should be familiar with the PDP-11 FORTRAN Language Reference 
Manual and the RT-lllRSTSIE FORTRAN TV User's Guide before using 
the material in this chapter. 

The system subroutine library provides the following capabilities: 

1. Complete RT-11 I/O facilities, including synchronous, asynchronous, 
and event-driven modes of operation. FORTRAN subroutines can be 
activated upon completion of an input/output operation. 

2. Timed scheduling of completion routines. This feature is standard in 
the FB and XM monitors, and is a special feature in the SJ monitor. 

3. Facilities for communication between foreground and background jobs. 

4. FORTRAN language interrupt service routines for user devices. 

5. Complete timer support facilities, including timed suspension of execu- 
tion in a FB or XM environment, conversion of different time formats, 
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and time-of-day information. The timer support facilities can use either 
50- or 60-cycle clocks. 

6. All RT-11 auxiliary input/output functions, including the capabilities 
of opening, closing, renaming, and creating or deleting files on any 
device. 

7. All monitor-level information functions, such as job partition parame- 
ters, device statistics, and input/output channel statistics. 

8. Access to the RT-11 command string interpreter (CSI). 

9. A character string manipulation package supporting variable-length 
character strings. 

10. INTEGER*4 support routines that allow two-word integer computa- 
tions. 

NOTE 

When variables are described or mentioned, and unless oth- 
erwise specified, INTEGER means INTEGER*2, (16-bit inte- 
ger) and REAL means REAL*4 (single-precision floating 
point). Integer and real arguments to subprograms are indi- 
cated in this section as follows: 

i = INTEGER*2 arguments 
j = INTEGER*4 arguments 
a = REAL*4 arguments 
d = REAL*8 arguments 

In general, the routines in SYSLIB were written for use with RT-11 V2 or 
later and FORTRAN IV VIB or later versions. The use of SYSLIB with 
prior versions of RT-11 or FORTRAN may lead to unpredictable results. 

1.2.1 System Conventions 

This section describes system conventions that must be followed for proper 
operation of calls to the system subroutine library. Certain restrictions that 
apply are described in Section 1.2.1.7. 

1.2.1.1 Channel Numbers — A channel number is a logical identifier for a 
file used by FORTRAN. Thus, when you open a file on a particular device, 
you assign a channel number to that file. To refer to an open file, it is only 

IXC^UC^OOCIX V ti\J J. OJ-OX l^\J bXXO C«.^^x vrjji^x xcXbCi vxxdxxxx^x xxu.xxi)^c;x . 

The FORTRAN system has 16(decimal) channels available for your use. 
The call IGETC assigns a channel to your program and notifies the FOR- 
TRAN I/O system, which also uses these channels, that the channel is in 
use. When there is no longer need for a channel, the program should close 
the channel with a CLOSEC, ICLOSE or a PURGE SYSLIB call. The chan- 
nel should also be freed and returned to the FORTRAN I/O system with a 
IFREEC call. 
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Up to 254(decimal) channels can be activated with the ICDFN call. This 
function sets aside memory in the job area to accommodate status informa- 
tion for the extra channels. Use the ICDFN call during the initialization 
phase of your program. You can use all channels numbered higher than 
15(decimal). The FORTRAN I/O system uses channels through 15(deci- 
mal). 

Channels must be allocated in the main program routine or its subpro- 
grams. Do not allocate channels in routines that are activated as the result 
of I/O completion events or ISCHED or ITIMER calls. 

1.2.1.2 Completion Routines — Completion routines can be written in FOR- 
TRAN or assembly language, depending upon the function called. 

A completion routine is a subprogram that executes asynchronously with a 
main program and is scheduled to run as soon as possible after the comple- 
tion of an associated event, such as an I/O transfer or the passing of a 
specified time interval. All completion routines of the current job have 
higher priority than other parts of the job. Therefore, once a completion 
routine becomes runnable because of its associated event, it interrupts exe- 
cution of the job and continues to execute until it relinquishes control. 

Completion routines are handled differently in the SJ and the FB and XM 
monitors. In the SJ monitor, these routines are totally asynchronous and 
can interrupt one another. Unlike completion routines run under FB and 
XM monitors, which are serialized and run at priority 0, completion 
routines run under an SJ monitor are nested and can interrupt each other. 
In addition, they execute not at priority 0, but at the same priority as the 
device whose interrupt scheduled them. For example, the completion rou- 
tine resulting from a .WRITC programmed request to device TT: runs at 
priority 4. Completion routines from timer requests run at the same prior- 
ity as the system clock. This is particularly important on LSI-11 and 
PDP/03 systems that have only two interrupt levels, ON and OFF, because 
clock interrupts may be lost while lengthy completion routines execute. In 
the FB and XM monitors, completion routines do not interrupt each other 
but are queued and have to wait until the correct job is running. They are 
then scheduled on a first-in first-out basis. 

Assembly language completion routines exit with an RTS PC instruction. 
FORTRAN completion routines exit by the execution of a RETURN or END 
statement in the subroutine. All names of completion routines external to 
the routine being coded that are passed to scheduling calls must be speci- 
fied in an EXTERNAL statement in the FORTRAN program unit issuing 
the call. 

A completion routine written in FORTRAN can have a maximum of two 
arguments as follows: 

Form: SUBROUTINE crtn [(iargl,iarg2)] 

where: 

crtn is the name of the completion routine 
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iargl is equivalent to RO on entry to an assembly language com- 
pletion routine 

iarg2 is equivalent to Rl on entry to an assembly language com- 
pletion routine 

If an error occurs in a completion routine or in a subroutine at completion 
level, the error handler traces back through to the original interruption of 
the main program. Thus, the traceback is shown as though the completion 
routine were called from the main program. This lets you know where the 
main program was executing, so that when an error is fatal, it can be 
diagnosed and corrected. 

Certain restrictions apply to completion routines that are activated by the 
following calls: 



INTSET 


IREADF 


ISPFNC 


IWRITC 


IRCVDC 


ISCHED 


ISPFNF 


IWRITF 


IRCVDF 


ISDATC 


ITIMER 


MRKT 


IREADC 


ISDATF 







The restrictions that apply when using these calls are as follows: 

® No channels can be allocated by calls to IGETC or freed by calls to 
IFREEC from a completion routine. Channels to be used by completion 
routines should be allocated and placed in a COMMON block for use by 
the routine. 

® The completion routine cannot perform any call that requires the use of 
the USR, such as LOOKUP and lENTER. See Section 1.2.1.5 for a list of 
the SYSLIB functions that call the USR. 

® Files that are used by the completion routine must be opened and closed 
by the main program. There are, however, no restrictions on the input or 
output operations that can be performed in the completion routine. If 
many files must be made available to the completion routine, they can be 
opened by the main program and saved for later use (without tying up 
RT-11 channels) by an ISAVES call. The completion routine can later 
make them available by reattaching the file to a channel with an IRE- 
OPN call. 

Even if the completion routine itself does not issue any programmed re- 
quests, but does perform I/O to a logical unit number through the OTS, 
that logical unit number must be opened from the main level. To accom- 
plish this, either the first I/O access or an OPEN statem-ent m-ust be 
issued from main level, A completion routine may not call CLOSE to close 
a logical unit. 

® FORTRAN subroutines are reusable but not reentrant. That is, a given 
subroutine can be used many times as a completion routine or as a rou- 
tine in the main program, but a subroutine executing as main program 
code does not work properly if it is interrupted and then called again at 
the completion level. This restriction applies to all subroutines that can 
be invoked at the completion level while they are active in the main 
program. 
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® FORTRAN completion routines can be called only by SYSLIB functions 
that end in F. Conversely, MACRO completion routines cannot be called 
by SYSLIB functions that end in F. Refer to Section 1.1.3.5 for details of 
other restrictions on MACRO completion routines. 

® Under the SJ monitor, only one completion function should be active at 
any time. 

1.2.1.3 Device Blocks — A device block is a four-word block of Radix-50 
information that specifies a physical device and a file name. In FORTRAN, 
you can use one of three different methods to set up this block as follows: 

1. You can use the DIMENSION and DATA statements. For example, 

DIMENSION IFILE (ii) 

DATA IFILE/3RSY .3RFILt3RE »3RXYZ/ 

2. You can translate the available ASCII file description string into Ra- 
dix-50 format, using the SYSLIB calls IRAD50, R50ASC, and RAD50. 
For example, 

REAL*8 FSPEC 

CALL IRAD50 (12» 'SY FILE XYZ'fFBPEC) 

3. You can use the SYSLIB call ICSI to call the Command String Inter- 
preter (CSI) to accept and parse standard RT-11 command strings. 

1 .2.1 .4 INTEGERM Support Functions — This section discusses the initializa- 
tion of INTEGER*4 variables for the FORTRAN programmer. Section 
1.2.6.3 describes the use of INTEGER*4 functions for use by the MACRO 
programmer. 

When the DATA statement is used to initialize INTEGER*4 variables, it 
must specify both the low- and high-order parts. For example, the code 

INTEGER*^ J 
DATA J/3/ 

Initializes only the first word. The correct way to initialize an INTEGER*4 
variable to a constant such as 3 is as follows: 

INTEGER*a J 

INTEGER*2 1(2) 

EQUIVALENCE (J»I) 

DATA 1/3.0/ ! INITIALIZE J TO 3 

If you are initializing an INTEGER*4 variable to a negative value such as 
—4, the high-order (second word) part must be the continuation of the two's 
complement of the low-order part. For example, 

INTEGER*^ J 

INTEGER*2 I (2) 

EOUiyALENCE (J, I) 

DATAI/-a»-l/ ! INITIALIZE J TO -^ 
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The following example is suitable for initializing INTEGER*4 arguments 
to subprograms: 



INTEGER»2 J(2) 

DATAJ/3tO/ !LOW ORDER»HIGH ORDER 



1.2.1.5 User Service Routine (USR) Requirements — User-written routines 
that interface to the FORTRAN Object Time System (OTS) must account 
for the location of the RT-11 User Service Routine (USR). The USR occu- 
pies 2K words. When your program calls a SYSLIB routine that requests a 
USR function (such as lENTER or LOOKUP), or when the USR is invoked 
by the FORTRAN OTS, the USR is swapped into memory if it is nonresi- 
dent. The FORTRAN OTS is designed so that the USR can swap over it. 

If you permit the USR to swap over certain kinds of data and code, you will 
obtain unpredictable results. In particular, you should restrict interrupt 
service routines and completion routines to locations outside the USR 
swapping area. To find the limits of this swapping area, examine the link 
map and, if necessary, change the order of object modules and libraries as 
specified to the Linker. 

Subroutines that require the USR are as follows: 

CLOSECICLOSE 

GETSTR (only if first I/O operation on logical unit) 
ICDFN (single job only) 
GTLIN 
ICSI 
' IDELET 
IDSTAT 
lENTER 
IFETCH 
IQSET 
IRENAM 

ITLOCK (only if USR is not in use by another job) 
LOCK (only if USR is in a swapping state) 
LOOKUP 
PUTSTR (only if first I/O operation on logical unit) 

CONTROLLING USR SWAPPING 

You can control USR swapping by using the KMON commands SET USR 
NOSWAP and SET USR SWAP. The SET USR NOSWAP command pre- 
vents swapping and freezes the USR in memory. The command SET USR 
SWAP reverses this, allowing the USR to swap under program control. 

Alternatively, you can compile your FORTRAN main program with the 
/NOSWAP option if you are sure that there is space just below the fore- 
ground partition or RMON to make the USR permanent for the duration of 
your program. Use this option if your program does not need the 2K words 
of memory that the USR occupies. If the /NOSWAP option is not specified, 
the USR swaps over the 2K words of your program above the base 
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address — that is, from location lOOO(octal) to llOOO(octal), which is the 
part of a FORTRAN program least likely to violate the USR restrictions. 

To prevent USR swapping for part of the program execution time and allow 
the USR to swap out at other times, use the LOCK, UNLOCK, and 
ITLOCK calls. 

The LOCK call locks the USR into main memory and attaches it to the 
requesting job. The UNLOCK call allows the USR to swap again and to be 
used by another job. The ITLOCK call is used to determine whether an- 
other job is already using the USR. If so, the ITLOCK call returns immedi- 
ately with an error code. This allows the program to try for a lock, but to 
continue with other action if it fails. The LOCK and UNLOCK calls are 
used in a foreground program to prevent interference from the background 
during initialization and completion phases and to minimize the number of 
swaps. 

STRATEGIES IN USR SWAPPING 

If you decide to change the position of code or data to avoid the USR swap- 
ping area, or if you want to move the USR itself, you must consider the 
concept of PSECT (program section) ordering. 

PSECTs contain code and data and are identified by names as segments of 
the object program. The attributes associated with each PSECT direct the 
Linker to combine several separately compiled FORTRAN program units, 
assembly language modules, and library routines into an executable pro- 
gram. 

The order in which program sections are allocated in the executable pro- 
gram is the order that they are presented to the Linker. Applications that 
are sensitive to this ordering typically separate those sections containing 
read-only information (such as executable code and pure data) from impure 
sections containing variables. 

The main program unit of a FORTRAN program (normally the first object 
module in sequence presented to LINK) declares PSECT ordering as shown 
in Table 1-6. 

The USR can swap over pure code, but must not be loaded over constants or 
impure data that can be used as arguments to the USR. The ordering 
shown in Table 1—6 collects all pure sections before impure data in memory. 
The USR can safely swap over sections OTS$I, OTS$P, SYS$I, USER$I, 
and $CODE. ¥7hen a FORTRAN program is running, the USR v/ill nor- 

xi.±a.x±y awa.^ oucxx bi.±i.g (Xu uxjii:^ k^cLo\^ \jx oov.^uj.v/j.x v^ j. k^t|/j.. j^\j\,a.vx\jLx ic\j v/j. uj.j.c: kjjrouo±i.x 

Communication Area contains the address where the USR will swap. If 
location 46 is zero, the USR will swap at its default location, below RMON 
and any handlers. 

See the RT-lllRSTSIE FORTRAN IV User's Guide for more information 
on program sections. The RT—11 Software Support Manual also contains 
information on USR swapping and PSECT ordering. 
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Table 1-6: FORTRAN Program PSECT Ordering 



Section Name 


Attributes 


OTS$I 


RW,I,LCL,REL,CON 


OTS$P 


RW,D,GBL,REL,OVR 


SYS$I 


RW,I,LCL,REL,CON 


USER$I 


RW,I,LCL,REL,CON 


$CODE 


RW,I,LCL,REL,CON 


OTS$0 


RW,I,LCL,REL,CON 


SYS$0 


RW,I,LCL,REL,CON 


$DATAP 


RW,D,LCL,REL,CON 


OTS$D 


RW,D,LCL,REL,CON 


OTS$S 


RW,D,LCL,REL,CON 


SYS$S 


RW,D,LCL,REL,CON 


$DATA 


RW,D,LCL,REL,CON 


USER$D 


RW,D,LCL,REL,CON 


.Ip{plpj|), 


RW,D,GBL,REL,OVR 


Other COMMON Blocks 


RW,D,GBL,REL,OVR 



USR LOCKOUT AND TIMING 

If one job is using the USR and another job requests it, the second job will 
become blocked until the first job releases the USR. The second job may be 
locked out for seconds or minutes at a time. Interrupt service and comple- 
tion routines can run, but not the mainline code. The timing problems that 
arise as a result can be eliminated, or minimized, in one of the following 
four ways: 

1. Do not use devices with slow directory operations, such as cassettes and 
magtapes. 

2. Code real-time operations as completion and interrupt service routines 
in your foreground job so that a locked out mainline program does not 
impact real-time operations. 

3. Separate USR and real-time operations. 

4. Use the ITLOCK call and avoid SYSLIB calls that request the USR 
while the USR is owned by another job. 

Typically, a real-time foreground job can be constructed of (1) an initializa- 
tion phase that opens all required channels and begins a real-time opera- 
tion, (2) a real-time phase that performs interrupt service and I/O opera- 
tions, and (3) a completion phase that halts real-time activity and then 
closes the channels. Maintaining this structure in the foreground allows 
the background task to do USR operations during the real-time phase with- 
out locking out the foreground. This also simplifies USR swapping since the 
USR can swap over the interrupt routines and I/O buffers as long as they 
are inactive. 

1.2.1.6 Subroutines Requiring Additional Queue Elements — Certain sub- 
routines require queue elements for their proper operation. These sub- 
routines are as follows: 
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IRCVD/IRCVDC/IRCVDF/IRCVDW 

IREAD/IREADC/IREADF/IREADW 

ISCHED 

ISDAT/ISDATC/ISDATF/ISDATW 

ISLEEP 

ISPFN/ISPFNC/ISPFNF/ISPFNW 

ITIMER 

ITWAIT 

lUNTIL 

IWRITC/IWRITE/IWRITF/IWRITW 

MRKT 

MWAIT 

One queue element per job is automatically allocated. Issuing more than 
one request from the list requires extra queue elements. Additional queue 
elements can be allocated through a call to the IQSET function. 

1.2.1.7 System Restriction — The following restrictions must be considered 
when coding a FORTRAN program that uses SYSLIB. 

1. Programs using IPEEK, IPOKE, IPEEKB, IPOKEB, or ISPY to access 
system-specific addresses, such as FORTRAN, monitor, or hardware 
addresses, are not guaranteed to run under future releases or on differ- 
ent configurations. When using these functions, you should document 
their use precisely so that you can check your references against the 
current documentation. Also, these routines may act differently under 
the XM monitor. NOTE: IPEEK and IPOKE are not equivalent to the 
programmed requests .PEEK and .POKE. 

2. Various functions in SYSLIB return values that are of type integer, 
real, and double precision. If you specify an implicit statement that 
changes the defaults for external function types, you must explicitly 
declare the type of those SYSLIB functions that return integer or real 
results. You must also be sure that the arguments to the SYSLIB 
routines are the correct type for the routine. Double-precision functions 
must always be declared to be type DOUBLE PRECISION (or 
REAL*8). Failure to observe this restriction leads to unpredictable re- 
sults. 

3. All names of completion routines external to the routine being coded 
that are passed to scheduling calls (such as ISCHED, ITIMER, and 
IREADC) must be specified in an EXTERNAL statement in the FOR- 

^^vJ.^^t jj^... VJ3* «."* *w^K, o ^ ^ 

4. Certain arguments to SYSLIB calls must be located in such a manner 
as to prohibit the RT-11 User Service Routine (USR) from swapping 
over them at execution time. This kind of swapping can occur when the 
OTS$I section (which contains the all-pure code and data for the mod- 
ule) is less than 2K words in length. Swapping in this uncommon situa- 
tion can be avoided either by typing the SET USR NOSWAP command 
to make the USR resident before starting the job, or by compiling the 
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mainline routine with a /NOSWAP option. You can also use the linker 
/BOUNDARY option to make OTS$0 start at word boundary 11000(oc- 
tal). (This problem generally occurs only with small FORTRAN pro- 
grams.) 

In FORTRAN IV, program sections (PSECTs) are used to collect code 
and data into appropriate areas of memory. If the RT-11 USR is needed 
and is not resident, it swaps over a FORTRAN program starting at the 
symbol OTS$I for 2K words of memory. 

5. Certain restrictions apply when using completion or interrupt routines. 
See Section 1.2.1.2 for a description of these restrictions. 

6. Unless explicitly stated, null arguments should not be used in calls to 
SYSLIB routines. 

7. If several arguments to a call are listed as being optional, they must 
either be all present or all omitted. 

1.2.2 Calling SYSLIB Subroutines 

SYSLIB includes both function subprograms and callable subroutines, 
which are called in the same manner as user- written subroutines. 

Function subprograms receive control by means of a function reference as 
follows: 

i = function name ([arguments]) 

The returned function value may be an error code, or it may be information 
that is useful to the calling routine. See the description of the particular 
function for the meaning of the returned function value. 

Call subroutines are invoked by means of a CALL statement as follows: 

CALL subroutine name [(arguments)] 

All subroutines in SYSLIB can be called as FUNCTION programs if a 
return value is desired, or as SUBROUTINE programs if no return value is 
desired. For example, the LOCK subroutine can be referenced as either 

CALL LOCK 

or 

I = LOCK( ) 

Some subroutines have two acceptable formats. For example, the subrou- 
tine CLOSEC can also be specified as ICLOSE because error codes are 
returned by the subroutine and require an integer return to be useful. 

Quoted-string literals are useful as arguments of calls to routines in SYS- 
LIB, notably the character string routines. These literals are allowed in 
subroutine and function calls (see Section 1.2.7.3). 
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1.2.3 FORTRAN/MACRO Interface 

FORTRAN calling routines and subroutines follow a well-defined set of 
conventions regarding transfer of control, transfer of information, memory 
usage, and register usage. By adhering to these conventions a MACRO 
programmer can write FORTRAN-callable routines such as those in SYS- 
LIB. 

Control is transferred to a subroutine by 

JSR PC.SUBR 

When control passes to the subroutine SUBR, Register 5 (R5) points to an 
argument block that has the format shown in Figure 1-5. 

Figure 1-5: Subroutine Argument Block 



R5=> 



Reserved 



No. of 
arguments 



Address of Argument 1 



Address of Argument 2 



Address of Argument n 



Null arguments in CALL statements must be entered with successive com- 
mas, for example, CALL SUBR (A„B). The value -1 is stored in the argu- 
ment block as the address of a null argument. 

The lower byte of the first word of the argument block contains the number 
of arguments that are passed to the subroutine. The rest of the argument 
block contains the addresses of those arguments. The argument block is 
n+ 1 words long for n arguments. 

The program counter is the linkage register. The subroutine outains its 
arguments through R5. In FORTRAN, the calling program saves the regis- 
ters, and the subroutine leaves the contents of the stack pointer intact 
before returning to the calling program. The RETURN statement of the 
subroutine is replaced by 

RTS PC 
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The name of the subroutine must be declared global with the .GLOBL 
directive in the calling program or with the double colon (::) construction in 
the called program. 

NOTE 

You must make sure that the called program does not modify 
the argument block passed by the calling program to a sub- 
program. 

1.2.3.1 Subroutine Register Usage — A subroutine that is called by a FOR- 
TRAN program does not have to preserve any registers. However, each 
push onto the stack must be matched by a pop off the stack before exiting 
from the routine. 

User-written assembly language programs must preserve any pertinent 
registers before calling FORTRAN subprograms or SYSLIB routines. They 
must then restore registers after the subroutine returns. 

Function subroutines return a single result in a register. Table 1-7 shows 
the register assignments for returning the different variable types. 

Table 1-7: Return Value Conventions for Function Subroutines 



Type 




Result Placed In 


INTEGER*2 
LOGICAL*! 


RO 




INTEGER*4 
L0GICAL*4 


RO 
Rl 


low-order result 
high-order result 


REAL 


RO 
Rl 


high-order result (including sign and exponent) 
low-order result 


DOUBLE PRECISION 


RO 
Rl 
R2 
R3 


highest-order result (including sign and exponent) 
next higher order 
next higher order 
lowest-order result 


COMPLEX 


RO 
Rl 
R2 
R3 


high-order real result 
low-order real result 
high-order imaginary result 
low-order imaginary result 



Note that floating-point results are returned in the general purpose regis- 
ters and not in the FPU registers. Assembly language subprograms that 
use the FPU Floating Point Unit may be required to save and restore the 
FPU status. 

1.2.3.2 FORTRAN Programs Caiiing MACRO Subroutines — FORTRAN pro- 
grams can call MACRO subroutines, but several rules must be followed. 
For example, the following program named INIARR is a MACRO subrou- 
tine that can be called from a FORTRAN program. 
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.TITLE INIARR 








.GLOBL INIARR 






1 


FILENAME INIARR. MAC 






INIARR: 


TST (R5)+ 


iSKIP ARGUMENT COUNT 






MOy (R5)+tR2 


5PUT ADDRESS OF ARRAY 


INTO R2 




MOy @<R5)+»R1 


iPUT lUAL IN Rl 






MOy @(R5)+»R0 


;AND COUNT INTO RO 






BLE RETURN 


iOUIT IF COUNT IS NOT 


POSITIUE 


1$: 


MOV Rl »(R2)+ 


.INITIALIZE ARRAY 






DEC RO 


;decrement count 






BNE 1* 


iCONTINUE UNTIL ZERO 




RETURN: 


RTS PC 
.END 







A FORTRAN program calls the preceding routine with 

CALL INIARR (IAR,IVAL,N) 
where: 

INIARR is the name of the subroutine 

lAR is the name of the array to initialize 

IV AL is the value the array is initialized to 

N is the number of elements to initialize 

This program illustrates the rules that must be observed when calling a 
MACRO program. The name of the subroutine is made global by using the 
.GLOBL directive. 

Register 5 (R5) is used to pass the arguments. Thus, in the program 
INIARR, the argument block would appear as shown in Figure 1-6. 

Figure 1-6: Argument Block for Program INIARR 

R5 => 



Address of lAR 



Address of IVAL 



Address of N 



Registers RO through R4 can be freely used since the calling program saves 
them. Once the arguments are retrieved, you can also use R5. 
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On completion, the subroutine returns to the calling program through an 
RTS PC. If your MACRO program pushes data on the stack, you must make 
sure that all data is popped off the stack before the RTS PC is executed. 

The following FORTRAN program named DOFOR calls the subroutine 
INIARR. 

PROGRAM DOFOR 
C 

INTEGER*2 ARRAY 

DIMENSION ARRAY(IO) 

N = 2 

DO 20 IMAL=1 .10 

CALL INIARR ( ARRAY . U'AL .N ) 

WRITE (5»100) (ARRAYd ) .1 = 1 .N) 
20 CONTINUE 
100 FORMAT (13) 

STOP 

END 

After you compile and link both programs, run the program by typing 

.RUN DOFOR m 

The initialized array will be output to the terminal as follows: 



2 

3 
3 

5 

5 
6 
B 
7 

7 

8. 

8 

9 

9 

10 

10 

STOP 



1.2.3.3 MACRO Routines Calling FORTRAN Programs — If you want to call 
FORTRAN subroutines from a MACRO program, create a dummy main 
program such as 

PROGRAM FORINT 
CALL CALMAC 
STOP 
END 
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where CALMAC is the name of a MACRO program that can call FOR- 
TRAN or MACRO routines. 

Creating a dummy program causes the FORTRAN main program to per- 
form the initialization necessary for FORTRAN subroutines. 

The following MACRO program named CALMAC calls a FORTRAN sub- 
routine named MAXMIN. 





.TITLE CALMAC 




.GLDBL MAXMIN 


CALMAC: 


. 




MOM #ARGBLK .R5 




JSR PCfMAXMIN 




RTS PC 


I : 


.WORD 28. 


J: 


.WORD 7B. 


ARGBLK: 


.WORD 2 




.WORD I 




.WORD J 




.END 



iPOINT R5 TO ARGUMENT BLOCK 
iCALL MAXMIN 

iMALUE OF FIRST ARGUMENT 
iUALUE OF SECOND ARGUMENT 
iNUMBER OF ARGUMENTS 
iADDRESS OF FIRST ARGUMENT 
iADDRESS OF SECOND ARGUMENT 



You must set up the argument block either on the stack or in a separate 
area in your MACRO program. You then point R5 to the top of the argu- 
ment block prior to calling the FORTRAN subroutine with a JSR PC .MAX- 
MIN. In the above program, the argument block is set up in a area of your 
program. 

The following program named STAKEM performs the same operation as 
the program CALMAC, except that it places the arguments on the stack. 





.TITLE 


STAKEM 




.GLOBL 


MAXMIN fSTAKEM 


STAKEM: 


MOU 


#J t-(SP) 




MOU 


«I »-(SP) 




Moy 


#2 ,-(SP) 




MOM 


SP »R5 




JSR 


PC .MAXMIN 




ADD 


#G ,SP 




RTS 


PC 


I : 


.WORD ; 


28. 


J: 


• WORD 
.END 


7G. 



If the argument block is set up on the stack, be sure that you remove the 
arguments from the stack prior to the execution of the RTS PC. In general, 
before calling the FORTRAN subroutine, you must save all pertinent regis- 
ters. You do not know which registers the FORTRAN subroutine is using. 
The stack pointer remains unchanged across the call. 

The name of the FORTRAN subroutine that the MACRO program calls 
must be defined as a global. In the FORTRAN subroutine, execute normal 
FORTRAN statements and return to the MACRO program with a RE- 
TURN statement. 
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The following program is the FORTRAN subroutine MAXMIN. 

SUBROUTINE MAXMIN ( INI .IN2) 

INTEGER BIGtSMALL 

IF ( INI .LT. IN2) GO TO 10 

BIG=IN1 

SMALL=IN2 

TYPE ZOjBIG 

TYPE 30. SMALL 

RETURN 
10 BIG=INZ 

SMALL=IN1 

TYPE 20 .BIG 

TYPE 30 .SMALL 
20 FORMAT ( ' THE BIGGER NUMBER IS ' .12) 
30 FORMAT ( ' THE SMALLER NUMBER IS ' ,12) 

RETURN 

END 

After assembling and linking the programs, using either the program CAL- 
MAC or STAKEM, type 



^ .RUN FORINT 



The program executes as follows: 

THE BIGGER NUMBER IS 7B 
THE SMALLER NUMBER IS 28 
STOP -- 

1.2.4 FORTRAN Programs in a Foreground/Background 
Environment 

FORTRAN programs can be run in a foreground/background environment, 
which permits efficient use of CPU execution time. (See Chapter 15 of 
Introduction to RT-11 for a description of running in an FB environment.) 
The basic steps in running FORTRAN programs that use the FB monitor 
are described in this section. 

Before running your foreground program, you must use the LOAD com- 
mand to load the device handlers required by the foreground job. The device 
handlers are placed in memory between RMON and the USR and KMON, 
which causes USR and KMON to move down in memory. 

Next, you use the FRUN command to load your foreground program in 
memory between the device handlers and the USR, which causes the USR 
and KMON to move further down in memory. It is important that you 
allocate workspace when running a FORTRAN program in the foreground. 
You do this with the /BUFFERm option of the FRUN command. Also make 
sure that any FORTRAN program you run in the foreground has adequate 
stack space. You can use one of the options supported by the linker (see the 
RT-11 System Utilities Manual). 

The background area must be at least 4K words long to accommodate the 
USR and KMON. Until you run a background job with the RUN command, 
KMON is the background job. 
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When the USR is required, a 2K-word area must be set up in each job for 
the swapping to occur correctly — that is, there must be space for 2K 
words in the background area and 2K words in the foreground area. USR 
swapping is explained in Section 1.2.1.5. 

1.2.4.1 Calculating Workspace for a FORTRAN Foreground Program — Addi- 
tional workspace must be allocated in memory when running a FORTRAN 
program in the foreground of a foreground/background environment. For a 
foreground job, the space is allocated by the /BUFFER:n option of the 
FRUN command. (A background job uses whatever space is available be- 
tween its high limit and the system's low limit.) When you allocate addi- 
tional workspace in memory to run a FORTRAN program in the fore- 
ground, calculate the space required by using the following formula: 

n = [l/2[504 + (35*N) + (R-136) + A*512]] 

where: 

n = number of decimal words 

A = the maximum number of files open at any one time. If double 
buffering is used, A should be multiplied by 2 

N = the maximum number of simultaneously open channels (logical 
unit numbers); the default is 6 

R = maximum formatted record length; the default is 136 charac- 
ters 

This formula must be modified for certain SYSLIB functions. 

The IQSET function requires the formula to include additional space for 
queue elements (qcount) as follows: 

n = [l/2[504 + (35*N) + (R-136) + A*512]] + [10*qcount] 

The ICDFN function requires the formula to include additional space for 
the integer number of channels {num) as follows: 

n = [l/2[504 + (35*N) + (R-136) + A*512]] + [6*num] 

The INTSET function requires the formula to include additional space for 
the number of INTSET calls issued in the program as follows: 

n - [l/2[504 + (35*N) + (R^136) + A*512]] + [25*INTSET] 

Any calls, including INTSET, that invoke completion routines must include 
64(decimal) words plus the number of words needed to allocate the second 
record buffer (default is 68[decimal] words). The length of the record buffer 
is controlled by the /RECORD option to the FORTRAN compiler. If the 
/RECORD option is not used, the allocation in the formula must be 136(dec- 
imal) bytes, or the length that was set at FORTRAN installation time. This 
modifies the formula as follows: 

n = [l/2[504 + (35*N) + (R-136) + A*512]] + [64 + R/2] 
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If the /BUFFER option does not allocate enough space in the foreground on 
the initial call to a completion routine, the following message appears: 

?Err Non-FORTRAN error call 

This message also appears if there is not enough free memory for the back- 
ground job or if a completion routine in the single-job monitor is activated 
during another completion routine. In the latter case, the job aborts; you 
should use the FB monitor to run multiple active completion routines. 

1.2.4.2 Running a FORTRAN Program in a Foreground/Bacl^ground 
Environment — This section briefly describes the procedure for running two 
FORTRAN programs, one in the background and one in the foreground. 

The background program named BACK is as follows: 

PROGRAM BACKGROUND 
IMPLICIT INTEGER(O) 

CALL I POKE ( "44. "10000. OR. I PEEK ("44) ) 
100 CALL PRINK 'HELLO FROM THE BACKGROUND') 
ICHAR=ITTINR<) 
OCHAR=ITTOUR(ICHAR) 
GO TO 100 
END 

This program prints the message "HELLO FROM THE BACKGROUND" 
and will print the message each time you input a character at the terminal. 

The foreground program named FORE is as follows: 

PROGRAM FOREGROUND 
IMPLICIT INTEGER(D) 

CALL I POKE ( "44 ."10000. OR. I PEEK ( "44) ) 
100 CALL PRINT( 'HELLO FROM THE FOREGROUND') 
ICHAR=ITTINR() 
OCHAR=ITTOUR(ICHAR) 
GO TO 100 
END 

After compiling both programs, link them. Link the foreground program 
using the LINK command with the /FOREGROUND option. This option 
produces a relocatable load module with a .REL file tj^pe. For example, 

.LINK/FOREGROUND FORE dS) 

Then you can assign the device that will be used for the output of the 
foreground program. You must also load into memory the peripheral device 
handlers needed by the foreground program. 

The command FRUN loads and starts execution of a .REL program as the 
foreground job. If the command 

.FRUN FORE M) 

is tj^ed at this point, the error message 

?Err G2 FORTRAN start fail 

will be displayed. This message indicates that additional workspace alloca- 
tion is required and that the /BUFFER option must be used. (Refer to the 
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previous section for the formula to calculate the additional space needed.) 
Thus, the command would be typed as follows: 

•FRUN F0RE/BUFFER:760 S) 

Execution of this command results in the following output at the terminal: 

F> 

HELLO FROM THE FOREGROUND 

B> 

* 

The system first identifies the message as foreground output. Then the 
foreground job executes and outputs its message. The background monitor 
next prrints the characters B> and a period, indicating that control has 
returned to monitor command mode. Command input remains directed to 
the background job. By typing 

.RUN BACK m 

the message from the background job will be displayed 

HELLO FROM THE BACKGROUND 

Each time a character is input to the terminal, say an "L", the message will 
be repeated. 

LHELLO FROM THE BACKGROUND 

Use the CTRL/F command to direct terminal input to the foreground job. 
The system prints F> to remind you that you are now directing input to the 
foreground job. When you type a character, such as "Y", the foreground job 
message will be displayed. 

F> 

YHELLO FROM THE FOREGROUND 

Type a CTRL/B to return to the background job or a CTRL/C to return to 
monitor command mode. If you are returning to a background environ- 
ment, you should unload the foreground job and any handlers to reclaim 
memory space for background use. 

1.2.5 Linking with FORLIB 

Normally, the default system library file (SYSLIB.OBJ) also includes the 
overlay handlers and the appropriate FORTRAN run-time system routines. 

To add FORLIB.OBJ modules to the default librar^"^ SYSLIB.OBJ use the 
following command: 



.LIBRARY/INSERT/REMOyE SYSLIB FORLIB 
Global? *Oi.iRH m 
Global? m 



1 .2.6 SYSLIB Services Not Provided by Programmed Requests 

SYSLIB provides many services that are not provided by programmed re- 
quests. Such services are as follows: 
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® Time conversion and date access 

® Program suspension 

® Two-word integer support (INTEGER*4) 

® Radix-50 conversion 

® Character string manipulation 

1.2.6.1 Time Conversion and Date Access — Several calls allow you to per- 
form time conversions and access the system date. 

You use the CVTTIM call to convert a two-word internal format time to 
hours, minutes, seconds, and ticks. The JTIME call converts a time given in 
hours, minutes, seconds, and ticks into the internal two-word time format. 

If you need to print out the time, the TIMASC call converts the time re- 
turned by the .GTIM programmed request into an eight-character ASCII 
string; the TIME call returns the current time of day as an eight-character 
ASCII string. 

The current system date can be accessed by your program with a DATE 
call. The date is returned as a string value. IDATE performs similarly, but 
returns an integer value. DATE and IDATE are part of FORLIB.OBJ. 

1 .2.6.2 Program Suspension — You suspend execution of a running program 
for a specified number of ticks with the ITWAIT call. You use the ISLEEP 
call to suspend a running program for a specified number of hours, minutes, 
seconds, and ticks. The lUNTIL call allows you to suspend job execution 
until a specific time of day, which is given to the routine in hours, minutes, 
seconds, and ticks. You can use this function to periodically collect data and 
to stop processing between acquisitions. 

1 .2.6.3 Two-Word Integer Support (INTEGER*4) — You can make calls to SYS- 
LIB to manipulate a 32-bit integer that uses two words of storage. The first 
word contains the low-order part of the value and the second word contains 
the sign and the high-order part of the value. The range of numbers that is 
represented is -2(31) to 2(31)-1. This format differs from the two-word 
internal time format that stores the high-order part of the value in the first 
word and the low-order part in the second word. Table 1-8 shows the calls 
that you can use to convert from one format to another. 

Table 1-8: SYSLIB Conversion Calls 



From 



To 



CaU 



INTEGER*2 (16-bit integer) INTEGER*4 

INTEGER*4 (32-bit integer) INTEGER*2 

INTEGER*4 REAL*4 

INTEGER*4 REAL*8 

REAL*4 (2-word floating point) INTEGER*2 

REAL*8 (4-word floating point) INTEGER*4 



JICVT 

UCVT 

AJFLT/IAJFLT 

DJFLT/IDJFLT 

JAFIX 

JDFIX 
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Calls are also available for you to perform arithmetic operations on 
INTEGER*4 values, move a value to a variable, and convert a two-word 
internal time format to and from an INTEGER*4 value. 

1.2.6.4 Radix-50 Conversion — You can convert ASCII characters to or from 
Radix-50. 

IRAD50 converts a specified number of characters of Radix-50 and returns 
the number of characters converted as a function result. RAD50 encodes 
RT-11 file descriptors in Radix-50 notation. R50ASC converts a specified 
number of Radix-50 characters to ASCII. 

1.2.6.5 Character String Operations — SYSLIB provides character string 
functions that perform string operations such as concatenation, compari- 
son, copying, replacing, and computing the number of characters in a 
string. For example, the following program will concatenate two character 
strings. 



, 


.TITLE GETTOO 




.GLOBL CONCAT 




• MCALL .PRINT ..EXIT 


START! 


MQi.' #ARGBLK.R5 




JSR PC. CONCAT 




.PRINT «STRCON 




.EXIT 


ARGBLK: 


.WORD 3 




.WORD STRNGl 




.WORD STRNGZ 




.WORD STRCON 


STRNGl: 


.ASCIZ /RESEARCH AND/ 


STRNG2: 


.ASCIZ / DEVELOPMENT/ 


STRCON: 


•BLKB 31 




.EVEN 




.END START 



Running this program results in the concatenation of string 1 and string 2, 
and the output at the terminal is 

RESEARCH AND DEVELOPMENT 

The following section describes character string functions in detail. 

1 .2.7 Character String Functions 

The SYSLIB character string functions and routines provide variable- 
length string support for RT-11 FORTRAN and for MACRO programs. 
SYSLIB calls perform the following character string operations: 

Call Operation 

GETSTR Reads character strings from a specified FORTRAN logical 
unit 

PUTSTR Writes character strings to a specified FORTRAN logical unit 

CONCAT Concatenates variable-length strings 
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INDEX Returns the position of one string in another 

INSERT Inserts one string into another 

LEN Returns the length of a string 

REPEAT Repeats a character string 

SCOMP Compares two strings 

SCOPY Copies a character string 

STRPAD Pads a string with blanks on the right 

SUBSTR Copies a substring from a string 

TRANSL Performs character modification 

TRIM Removes trailing blanks 

VERIFY Verifies the presence of characters in a string 

Strings are stored in LOGICAL*! arrays that you define and dimension. 
These arrays store strings in ASCII format as one character per array 
element plus a zero element to indicate the current end of the string. 

The length of a string can vary at execution time from zero characters to 
one less than the size of the array that stores the string. The maximum size 
of any string is 32767 characters. Strings can contain any of the seven-bit 
ASCII characters except null(O), since the null character is used to mark 
the end of the string. The inclusion of a terminating zero byte constitutes 
an "ASCIZ" format, which is the format set up by a MACRO assembler 
directive .ASCIZ. This directive automatically sets up strings with a termi- 
nating zero byte. Bit 7 of each character must be cleared. Therefore, the 
valid characters are those whose decimal representations range from 1 to 
127, inclusive. 

The ASCII code used in this string package is the same as that employed by 
FORTRAN for A-type FORMAT items, ENCODE/DECODE strings, and 
object- time format strings. Whenever quoted strings are used as arguments 
in the CALL statement, ASCIZ strings are generated for these routines by 
the FORTRAN compiler. Note that a null string (a string containing no 
characters) can be represented in FORTRAN by a variable or constant of 
any type that contains the value zero, or by a LOGICAL variable or con- 
stant with the .FALSE, value. 

In many routines, it is difficult to predict the length of the string produced. 
To nrevent a strino" from overflowino' the arra'" that contains it ■*'ou can 
specify an optional integer argument to the subroutine. This argument, 
called len, limits the length of an output string to the value specified for len 
plus one (for the null terminator), so that the array receiving the result 
must be at least len plus one elements in size. 

NOTE 

If the string is larger than the array, other data may be 
destroyed and cause unpredictable results. 
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When len is specified, you can also include the optional argument called 
err. Err is a logical variable that should be initialized by the FORTRAN 
program to the .FALSE, value. If a string function is given the arguments ) 

len and err, and len is actually used to limit the length of the string result, 
then err is set to the .TRUE, value. If len is not used to truncate the string, 
err is unchanged — that is, it retains a .FALSE, value. 

The argument len can appear alone. However, len must appear if err is 
specified. The err argument should be used for GETSTR and PUTSTR. 

Several routines use the concept of character position. Each character in a 
string is assigned a position number. The first character in a string is in 
position one. Each subsequent character has a position number one greater 
than the character that precedes it. 

1.2.7.1 Allocating Character String Variables — A one-dimensional LOGI- 
CAL*! array can contain a single string whose length can vary from zero 
characters to one fewer than the dimensioned length of the array. For ex- 
ample, I 

LOGICAL*! A(a5) lALLOCATE SPACE FDR STTylNG UARIABLE A 

allows array A to be used as a string variable that can contain a string of 
44 or fewer characters. Similarly, a two-dimensional LOGICAL*! array 
can be used to contain a one-dimensional array of strings. Each string in 
the array can have a length up to one less than the first dimension of the 
LOGICAL*! array. There can be as many strings as the number specified 
for the second dimension of the LOGICAL*! array. For example, ) 

LOGICAL*! W(2! »!0) lALLOCATE AN ARRAY OF STRINGS 

creates string array W that has ten string elements, each of which can 
contain up to 20 characters. String I in array W is referenced in subroutine 
or function calls as W(!,I). 

The following example allocates a two-dimensional string array. 

LOGICAL*! T(14»5. 7) ! ALLOCATE A 5 BY 7 ARRAY OF ! 3-CHARACTER ) 

ISTRINGS 

Each string in array T may vary in length to a maximum of !3 characters. 
String I,J of the array can be referenced as T(!,I,J). Note that T is the same 
as T(!,!,!). This dimensioning process can create string arrays of up to six 
dimensions (represented by LOGICAL*! arrays of up to seven dimensions). 

•t f\ ^ r% n.^^i.^^ ^*..;m^«. i.^ c«..u.»-^«-.»... rpi i.1 i.~ 

i.c.i.e. i-assiiiy oiiiiiys lu ouuj^iuyiaiiia — xiicie arc Liiicc ways uu pass 

strings to subprograms. 

!. LOGICAL*! arrays that contain strings can be placed in a COMMON 
block and referenced by any or all routines with a similar common 
declaration. However, when you place a LOGICAL*! array in a com- 
mon block, make sure that the array is even in length, that odd-length 
arrays are paired to result in an overall even length, or that the strings 
are together as the last elements in the COMMON block. Otherwise, all ) 
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succeeding variables in the COMMON block may be assigned odd ad- 
dresses. 

A LOGICAL*! array has an odd length only if the product of its dimen- 
sions is odd. For example, 

LOGICAL*! BdO. 7) !(10*7) = 70 i EUEN LENGTH 
LOGICAL*! H (2!) !2! IS AN ODD LENGTH 

These might be handled as follows: 

COMMON A! »A2,A3(!0) >H(21) ! PLACE ODD-SIZED ARRAY AT END 

or 

COMMON A! »A2.H(2!) >H! (7) tA3( !0) !PAIR ODD-SIZE ARRAYS H AND HI 

These restrictions apply only to LOGICAL*! variables and arrays. 

A single string can be passed by using its array name as an argument. 
For example, 

LOGICAL*! A(2!) [STRING VARIABLE A. 20 CHARACTERS MAXIMUM 
CALL SUBR(A) 

passes string A to subroutine SUBR. 

If the calling program has declared a multidimensional array, and only 
one string of that array is to be passed to a subroutine, then the subrou- 
tine call should specify the first element of the string to be passed (this 
requires that the first dimension of the array equals the maximum 
length of each string). 

For example, 

LOGICAL*! NAMES (e!.20) !20 NAMES* 80 CHARACTERS EACH 
LOGICAL*! ERR 



DO !0 NAMNUM=1 (20 ! GET ALL 20 NAMES 
!0 CALL GETSTR ( 5 (NAMES ( ! »NAMNUM ) >80 tERR ) IFROMTT 

If the maximum length of a string argument is unknown in a subroutine or 
function, or if the routine is used to handle many different lengths, the 
dummy argument in the routine should be declared as a LOGICAL*! array 
with a dimension of one, such as LOGICAL*! ARG(!). In this case, the 
string routines correctly determine the length of ARG whenever it is used, 
but it is not possible to determine the maximum size of any string that can 
be stored in ARG. If a multidimensional array of strings is passed to a 
routine, it must be declared in the called program with the same dimen- 
sions that were specified in the calling program. 

NOTE 

The length argument specified in many of the character 
string functions refers to the maximum length of the string 
excluding the necessary null byte terminator. The length of 
the LOGICAL*! array to receive the string must be at least 
one greater than the length argument. 
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1.2.7.3 Using Quoted-String Literals — You can use quoted strings as argu- 
ments to any of the string routines that are invoked as functions or with 
the CALL statement. For example, 

CALL SCOMP(NAME , 'SMYTHE* R' ,M) 

compares the string in the array NAME to the constant string SMYTHE, R 
and sets the value of the integer variable accordingly. 

1.2.8 System Subroutine Summary 

Table 1-9 lists the SYSLIB subroutines alphabetically within categories, 
the sections in which they are located, and a brief description of each sub- 
routine. Those subroutines prefaced with an asterisk (*) are allowed only in 
a foreground/background environment, under either the FB or XM monitor. 
The SYSLIB subroutines do not support the XM monitor mapping pro- 
grammed requests. Use FORTRAN virtual arrays to access extended mem- 
ory. 

Table 1-9: Summary of SYSLIB Subroutines 



Name 



Section 



Description 



File-Oriented Operations 



CLOSEC, 


3.3 


ICLOSE 




IDELET 


3.22 


lENTER 


3.25 


IFPROT 


3.27 


IRENAM 


3.46 


ISFDAT 


3.53 


LOOKUP 


3.79 



Closes the specified channel. 

Deletes a file fi-om the specified device. 

Creates a new file for output. 

Changes the file's protection. 

Changes the name of the indicated file. 

Changes the file's creation date. 

Opens an existing file for input and/or output via the speci- 
fied channel. 



Data Transfer Operations 

lABTIO 3.12 Aborts I/O operations on a specified channel. 

GTLIN 3.11 Transfers a line of input from the console terminal or indi- 

rect file (if active) to the user program. 

*IRCVD 3.44 Receives data. Allows a job to read messages or data sent by 

*IRCVDC another job in an FB environment. The four modes corre- 

*IRCVDF spond to the IREAD, IREADC, IREADF, and IREADW 

*IRCVDW modes. 

IREAD 3.45 Transfers data from a file to a memory buffer and returns 

control to the user program when the request is entered in 
the I/O queue. No special action is taken upon completion of 
I/O. 



FB and XM monitors only. 



(continued on next page) 
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Table 1-9: Summary of SYSLIB Subroutines (Cont.) 



Name 



Section 



Description 



IRE ADC 



3.45 



IREADF 



IWRITC 

IWRITE 
IWRITF 

IWRITW 

tMTATCH 

tMTDTCH 

tMTIN 

tMTOUT 

tMTPRNT 



3.45 



IREADW 


3.45 


*ISDAT 


3.51 


*ISDATC 




*ISDATF 




*ISDATW 




ITTINR 


3.59 


ITTOUR 


3.60 


IWAIT 


3.64 



3.65 

3.65 
3.65 

3.65 
3.81 
3.82 

O QQ 

3.84 
3.85 
3.86 



Transfers data from a file to a memory buffer and returns 
control to the user program when the request is entered in 
the I/O queue. Upon completion of the read, control transfers 
to the assembly language routine specified in the IREADC 
function call. 

Transfers data from a file to a memory buffer and returns 
control to the user program when the request is entered in 
the I/O queue. Upon completion of the read, control transfers 
to the FORTRAN subroutine specified in the IREADF func- 
tion call. 

Transfers data from a file to a memory buffer and returns 
control to the program only after the transfer is complete. 

Allows the user to send messages or data to the other job in 
an FB environment. The four functions correspond to the 
IWRITE, IWRITC, IWRITF, and IWRITW modes. 

Gets one character from the console keyboard. 

Transfers one character to the console terminal. 

Waits for completion of all I/O on a specified channel (com- 
monly used with the IRE AD and IWRITE functions). 

Transfers data to a file and returns control to the user pro- 
gram when the request is entered in the I/O queue. Upon 
completion of the write, control transfers to the assembly 
language routine specified in the IWRITC function call. 

Transfers data to a file and returns control to the user pro- 
gram when the request is entered in the I/O queue. No spe- 
cial action is taken upon completion of the I/O. 

Transfers data to a file and returns control to the user pro- 
gram when the request is entered in the I/O queue. Upon 
completion of the write, control transfers to the FORTRAN 
subroutine specified in the IWRITF function call. 

Transfers data to a file and returns control to the user pro- 
gram only after the transfer is complete. 

Attaches a particular terminal in a multiterminal environ- 
ment. 

Detaches a particular terminal in a multiterminal environ- 
ment. 



terminal system. 

Transfers characters from a specific terminal to the user pro- 
gram in a multiterminal system. 

Transfers characters to a specific terminal in a multitermi- 
nal system. 

Prints a message to a specific terminal in a multiterminal 
system. 

^ With multiterminal support only. (continued on next page) 

* FB and XM monitors only. 
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Table 1-9: Summary of SYSLIB Subroutines (Cont.) 



Name 



Section 



Description 



Enables output to terminal by canceling the effect of a previ- 
ously typed CTRL/0. 

Sets terminal and line characteristics in a multiterminal 
system. 

Returns multiterminal system status. 

Waits for messages to be processed. 

Outputs an ASCII string to the console terminal. 

ions 

Defines additional I/O channels. 

Allows access to files currently open in another job's envi- 
ronment. 

Returns the status of a specified channel. 

Returns the specified RT-11 channel to the available pool of 
channels for the FORTRAN I/O system. 

Allocates an RT-11 channel and informs the FORTRAN I/O 
system of its use. 

Returns the RT-11 channel number with which a FOR- 
TRAN logical unit is associated. 

Restores the parameters stored via an ISAVES function and 
reopens the channel for I/O. 

Stores five words of channel status information into a user- 
specified array and deactivates the channel. 

Deactivates a channel. 



tMTRCTO 


3.87 


tMTSET 


3.88 


tMTSTAT 


3.89 


*MWAIT 


3.90 


PRINT 


3.91 


Channel-Oriented Oi 


ICDFN 


3.16 


*ICHCPY 


3.17 


ICSTAT 


3.21 


IFREEC 


3.28 


IGETC 


3.29 


ILUN 


3.33 


IREOPN 


3.47 


ISAVES 


3.48 


PURGE 


3.92 



Device and File Specifications 

lASIGN 3.15 Sets information in the FORTRAN logical unit table 

ICSI 3.20 



Calls the RT-11 CSI in special mode to decode file specifica- 
tions and options. 



Timer Support Operations 



CVTTIM 

GTIM 
ICMKT 

ISCHED 
ISDTTM 



3.5 Converts a two-word internal format time to hours, minutes, 

seconds, and ticks. 

3.9 Gets time of day. 

3.19 Cancels an unexpired ISCHED, ITIMER, or MRKT request 

(valid under FB and XM, and for SJ monitors with timer 
support, a SYSGEN option). 

3.49 Schedules the specified FORTRAN subroutine to be entered 

at the specified time of day as an asynchronous completion 
routine (valid under FB and XM, and for SJ monitors with 
timer support, a special feature). 

3.52 Changes the system date and time. 



^ With multiterminal support only. 
* FB and XM monitors only. 



(continued on next page) 
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Table 1-9: Summary of SYSLIB Subroutines (Cont.) 



Name 



Section 



Description 



tISLEEP 



ITIMER 



3.54 



3.57 



HTWAIT 


3.61 


tlUNTIL 


3.62 


JTIME 


3.76 


MRKT 


3.80 



SECNDS 


3.103 


TIMASC 


3.108 


TIME 


3.109 


RT-11 Services 




CHAIN 


3.2 


♦DEVICE 


3.6 


G-TJB.IGTJB 


3.10 


IDSTAT 


3.24 


IFETCH 


3.26 


IQSET 


3.42 


ISPFN 


3.55 


iSFFCN 




ISPFNF 




ISPFNW 




*ITLOCK 


3.58 


LOCK 


3.78 



Suspends main program execution of the running job for a 
specified amount of time; completion routines continue to 
run. 

Schedules the specified FORTRAN subroutine to be entered 
as an asynchronous completion routine when the time inter- 
val specified has elapsed (valid under FB and XM, and for 
SJ monitors with timer support, a special feature). 

Suspends the running job for a specified amount of time; 
completion routines continue to run. 

Suspends the main program execution of the running job 
until a specified time of day; completion routines continue to 
run. 

Converts hours, minutes, seconds, and ticks into two-word 
internal format time. 

Schedules an assembly language routine to be activated as 
an asynchronous completion routine after a specified inter- 
val (valid under FB and XM, and for SJ monitors with timer 
support, a special feature). 

Returns the current system time in seconds past midnight 
minus the value of a specified argfument. 

Converts a specified two-word internal format time into an 
eight-character ASCII string. 

Returns the current system time of day as an eight-charac- 
ter ASCII string. 



Chains to another program (from the background job only). 

Specifies actions to be taken on normal or abnormal pro- 
gram termination, such as turning off interrupt enable on 
user-programmed devices. 

Returns the parameters of the specified job. 

Returns the status of the specified device. 

Loads a device handler into memory. 

Expands the size of the RT-11 monitor queue from the free 
space managed by the FORTRAN system. 

Issues special function requests to various handlers, such as 
magtape, me lOur moues corresponu 
IWRITC, IWRITF, and IWRITW modes. 



i mi- _ c l-_ i i_ il T^irDTT^i:^ 

magtape, xiie luur iiiuues cuix espuixu tu liic xvvxvxxiu, 



Indicates whether the USR is currently in use by another job 
and performs a LOCK if the USR is available. 

Makes the RT-11 monitor User Service Routine (USR) per- 
manently resident until an UNLOCK function is executed. 
If necessary, a portion of the user's program is swapped out 
to make room for the USR. 



* SYSGEN option in SJ monitor. 

* FB and XM monitors only. 



(continued on next page) 
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Name 



Section 



Description 



RCHAIN 3.96 Allows a program to access variables passed across a chain. 

RCTRLO 3.97 Enables output to the terminal by canceling the effect of a 

previously typed CTRL/0. 

♦RESUME 3.99 Causes the main program execution of a job to resume at the 

point it was suspended by a SUSPND function call. 

SCCA 3.100 Intercepts a CTRL/C command initiated at the console ter- 

minal. 

SETCMD 3.104 Passes command lines to the keyboard monitor for execution 

after the program exits. 

♦SUSPND 3.107 Suspends main program execution of the running job; com- 

pletion routines continue to execute. 

UNLOCK 3.112 Releases the USR if a LOCK was performed; the user pro- 

gram is swapped in if required. 

INTEGER*4 Support Functions 

Converts a specified INTEGER*4 value to REAL*4 and re- 
turns the result as the function value. 

Converts a specified INTEGER*4 value to REAL*8 and re- 
turns the result as the function value. 

Converts a specified INTEGER*4 value to REAL*4 and 
stores the result. 

Converts a specified INTEGER*4 value to REAL*8 and 
stores the result. 

Converts a specified INTEGER*4 value to INTEGER*2. 

Computes the sum of two INTEGER*4 values. 

Converts a REAL*4 value to INTEGER*4. 

Compares two INTEGER*4 values and returns an 
INTEGER*2 value that reflects the signed comparison re- 
sult. 

Converts a REAL*8 value to INTEGER*4. 

Computes the quotient and remainder of two 
INTEGER*4 values. 

Converts an INTEGER*2 value to INTEGER*4. 

Converts the two-word internal time format to 
INTEGER*4 format, and vice versa. 

Assigns an INTEGER*4 value to a variable. 

Computes the product of two INTEGER*4 values. 

Computes the difference between two INTEGER*4 
values. 

FB and XM monitors only. (continued on next page) 



AJFLT 


3.1 


DJFLT 


3.7 


lAJFLT 


3.14 


IDJFLT 


3.23 


IJCVT 


3.32 


JADD 


3.66 


JAFIX 


3.67 


JCMP 


3.68 


JDFIX 


3.69 


JDIV 


3.70 


JICVT 


3.71 


JJCVT 


3.72 


JMOV 


3.73 


JMUL 


3.74 


JSUB 


3.75 
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Name 



Section 



Description 



Character String Functions 

CONCAT 3.4 

GETSTR 3.8 



Concatenates two variable-length strings. 



INDEX 



3.34 



INSERT 


3.35 


ISCOMP 


3.50 


IVERIF 


3.63 


LEN 


3.77 


PUTSTR 


3.93 


REPEAT 


3.98 


SCOMP 


3.101 


SCOPY 


3.102 


STRPAD 


3.105 


SUBSTR 


3.106 


TRANSL 


3.110 


TRIM 


3.111 


VERIFY 


3.113 



Reads a character string from a specified FORTRAN logical 
unit. 

Returns the location in one string of the first occurrence of 
another string 

Replaces a portion of one string with another string. 

Compares two character strings. 

Indicates whether characters in one string appear in an- 
other. 

Returns the number of characters in a specified string. 

Writes a variable-length character string on a specified 
FORTRAN logical unit. 

Concatenates a specified string with itself to provide an indi- 
cated number of copies and stores the resultant string. 

Compares two character strings. 

Copies a character string from one array to another. 

Pads a variable-length string on the right with blanks to 
create a new string of a specified length. 

Copies a substring from a specified string. 

Replaces one string with another after performing character 
modification. 

Removes trailing blanks from a character string. 

Indicates whether characters in one string appear in an- 
other. 



Radix-50 Conversion Operations 

IRAD50 3.43 Converts characters in ASCII format to Radix-50, 

returning the number of characters converted. 

R50ASC 3.94 Converts characters in Radix-50 format to ASCII. 

RAD50 3.95 Converts six ASCII characters, returning a REAL*4 

result that is the two-word Radix-50 value. 



Miscellaneous Services 



IGETSP 



INTSET 



IPEEK 



O 1 O /^ W4- n i vk o ^-V>o -rrtc^rY^mrrr aAAfCkoa rtf q artOi/>i fl curl OTlflfv 

3.30 Returns the address and size (in words) of free space ob- 

tained from the FORTRAN system. 

3.36 Establishes a specified FORTRAN subroutine as an inter- 
rupt service routine with a specified priority. 

3.37 Returns the value of a word located at a specified absolute 
memory address. 

(continued on next page) 
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Name Section Description 

IPEEKB 3.38 Returns the value of a byte located at a specified byte ad- 

dress. 

Stores an integer value in an absolute memory location. 

Stores an integer value in a specified byte location. 

Changes the value of the word located at an offset specified 
from the beginning of the RT-11 monitor. 

ISPY 3.56 Returns the integer value of the word located at a specified 

offset from the beginning of the RT-11 resident monitor. 



IPOKE 


3.39 


IPOKEB 


3.40 


IPUT 


3.41 
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Chapter 2 

Programmed Request Description and Examples 



This chapter presents the programmed requests alphabetically, describing 
each one in detail and providing an example of its use in a program. Also 
described are macros and subroutines that are used to implement device 
handlers and interrupt service routines. The following parameters are com- 
monly used as arguments in the various calls: 

addr an address, the meaning of which depends on the request 

being used. 

area a pointer to the EMT argument block for those requests 

that require a block. 

blk a block number specifying the relative block in a file or 

device where an I/O transfer is to begin. 

buf a buffer address specifying a memory location into which 

or from which an I/O transfer will be performed; this ad- 
dress has to be word-aligned — that is, located at an even 
address and not a byte or odd address. 

cblk the address of the five-word block where channel status 

information is stored. 

chan a channel number in the range 0-376(octal). 

chrcnt a character count in the range l-255(decimal). 

code a flag used to indicate whether the code is to be set in an 

EMT 375 programmed request. 

crtn the entry point of a completion routine. 

dblk a four-word Radix-50 descriptor block that specifies the 

physical device, file name, and file type to be operated 
upon (see Section 1.1.2.6). 

func a numerical code indicating the function to be performed. 

jobblk a pointer to a three-word ASCII system job name. 

jobdev a pointer to a four-word system-job descriptor where the 
first word is a Radix-50 device name and the next three 
words contain an ASCII system-job name (for keyword ar- 
gument use, refer to this as a "dblk"). 

num a number, the value of which depends on the request. 



2-1 



seqnum a file number. 



For cassette operation, a value of is assumed if this argu- 
ment is blank. 

For magtape operation, this argument describes a file se- 
quence number. The values that the argument can have 
are described under the applicable programmed requests. 

the logical unit number of a particular terminal in a mul- 
titerminal system. 

a word count specifying the number of words to be trans- 
ferred to or from the buffer during an I/O operation. 

Many programmed requests are qualified as special features. These re- 
quests are enabled only if you performed a system generation process, that 
is, they are not available in a distributed monitor. 



unit 



went 



2.1 .ABTIO 



The .ABTIO programmed request allows a running job to stop all outstand- 
ing I/O operations on a channel without terminating the program. 

When .ABTIO is issued, the handler for the device opened on the specified 
channel is entered at its abort entry point. After the handler abort code is 
executed, control returns to the user program. 

This request cannot be issued from a completion routine. 

Macro Call: .ABTIO chan 

where: 

chan is the channel number for which to abort I/O 
Request Format: 
RO = 
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chan 



Errors: 

none 
Example: 



.TITLE ABTIO. MAC 
iThis is an example of the .ABTIO re-iuest. The .ABTIO request 
lis useful for immediately terminatinS .READC/ .WRITC or .READ/ 
i. WRITE I/O on a particular channel without issuins a lEXIT or 
i.HRESETi which would terminate the proSram or stop I/O on all 
ichannels > 



START: 



lOLOOP! 



.MCALL 



.SCCA 
.ENTER 



.ABTIO, .ENTER. .SCCA 

»AREA,»CTCWRD 
«AREA.»1 .SFILNAM 



ilnhibit CTRL/C 

iOpen channel 1 as output file 

iPerform I/O to the file... 
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TST 


CTCWRD 






BPL 


lOLOQP 






.fiBTID 


al 




AREA: 


■ BLKW 


a 




CTCWRD: 


.WORD 
.END 





2.2 


.ADDR 







;Ha5 CTRL/C been typed? 
iNo) continue file I/O 
iYesi stop I/O on channel 1 

iContinue other process! n 3 



iEMT arsument blocK 
iTerminal status word 



The .ADDR macro computes the address you specify in a position-independ- 
ent manner. 

The .ADDR macro has the following syntax: 

.ADDR addr,reg,push 



where: 



addr is the label of the address to compute, expressed as an imme- 
diate value with a number sign (#) before the label. 

reg is the register in which to store the computed address, ex- 
pressed as a register reference Rn or @Rn. To store the ad- 
dress on the stack, use @SP or -(SP). The following register 
references are valid: 



Rl 


@R1 


@SP 


R2 


@R2 


-(SP) 


R3 


@R3 




R4 


@R4 




R5 


@R5 
@R6 





push 



determines what to do with the original contents of the regis- 
ter. If you omit push, the computed address overwrites the 
register contents. If you use ADD for the push argument, the 
computed address is added to the original contents of the reg- 
ister. If you use PUSH for the push argument, the register 
contents are pushed onto the stack before the computed ad- 
dress is stored in the register. 

If you use -(SP) for the argument reg and you omit the push 
argument, PUSH is automatically used. 

The following sample lines from a program show all three uses of the 
.ADDR macro. 

iLOAD ADDRESS OF ABC IN RO 

!ADD ADDRESS OF LABEL TO CONTENTS 
iOF RO 

■ PUSH CONTENTS OF RO ONTO STACK . 
;THEN LOAD ADDRESS OF ABC IN RO 



ADDR 


• ABC 


(RO 


ADDR 


«ABC 


iRO.ADD 


ADDR 


»ABC 


.RO.PUSH 
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2.3 .ASSUME 



2.4 .BR 



The .ASSUME macro tests for a condition you specify. If the test is false, 
MACRO generates an assembly error and prints a descriptive message. 

The .ASSUME macro has the following syntax: 

.ASSUME a rel c [message = text] 

where: 

a is an expression. 

c is an expression. 

rel is the relationship between a and c you want to test. 

text is the message you want MACRO to print if the condition you 
specified in the relationship between a and c is false. To spec- 
ify your own error message, start the message with a semico- 
lon (;), or start with a valid assembly expression followed by 
a semicolon (;) and the message. If you omit the message 
argument, the error message "a REL c" IS NOT TRUE 
prints; the expressions you used appear in the message in 
place of a and c. 

In the following example, if the location counter (.) is less than 1000, 
MACRO generates an assembly error and prints the message 1000 - '• 
LOCATION TOO HIGH. ge it/i/i/ ., 

.ASSUME . LT 1000 MESSflGE=< 1000- . iLOCATION TOD HIGH> 



The .BR macro warns you if code that belongs together is separated during 
assembly. When you call the .BR macro, you specify an address as an argu- 
ment. .BR checks that the next address matches the address you specified 
in the .BR macro. If it does not, MACRO prints the error message Error- not 
at location "addr". The location you specified in the .BR macro appears in 
place of addr in the message. 

The .BR macro has the following syntax: 

.BR addr 

where addr is the address you want to test. 

In the following example, MACRO tests the location that follows the .BR 
macro. Since the address does not match the address ABC, MACRO prints 
an error message. 

PjjQ. '^^ '^^^ 'TEST THE NEXT ADDRESS FOR ABC 



ABC: 
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In the next example, no error occurs: 



.BR DEF 
DEF: 



2.5 .CDFN 



The .CDFN request redefines the number of I/O channels. Each job, 
whether foreground or background, is initially provided with 16(decimal) 
I/O channels numbered 0-15. .CDFN allows the number to be expanded to 
as many as 255(decimal) channels (0-254 decimal, or 0-376 octal). Channel 
377 is reserved for use by the monitor. 

The space for the new channels is taken from within the user program. 
Each I/O channel requires five words of memory. Therefore, you must allo- 
cate 5*n words of memory, where n is the number of channels to be defined. 

It is recommended that you use the .CDFN request at the beginning of a 
program before any I/O operations have been initiated. If more than one 
.CDFN request is used, the channel areas must either start at the same 
location or not overlap at all. The two requests .SRESET and .HRESET 
cause the channels to revert to the original 16 channels defined at program 
initiation. Hence, you must reissue any .CDFNs after using .SRESET or 
.HRESET. The keyboard monitor command CLOSE does not work if your 
program defines new channels with the .CDFN request. 

The .CDFN request defines new channels so that the space for the previ- 
ously defined channels cannot be used. Thus, a .CDFN for 20(decimal) 
channels (while 16 original channels are defined) creates 20 new I/O chan- 
nels; the space for the original 16 is unused, but the contents of the old 
channel set are copied to the new channel set. 

If a program is overlaid, the overlay handler uses channel 17(octal) and this 
channel should not be modified. (Other channels can be defined and used as 
usual.) 

In an XM monitor environment, the area supplied for additional channels 
specified by the .CDFN request must lie in the lower 28K words of memory. 
In addition, it must not be in the virtual address space mapped by Kernel 
PARI, specifically the area from 20000 to 37776(octal). If you supply an 
invalid area, the system generates an error message. 

Macro Call: .CDFN area,addr,num 

where: 

area is the address of a three-word EMT argument block 

addr is the address where the I/O channels begin 

num is the number of I/O channels to be created 
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Request Format: 
RO — > area: 



Errors: 



Example: 



15 







addr 



num 



Code Explanation 

An attempt was made to define fewer than or the same num- 

ber of channels that already exist. In an XM environment, 
an attempt to violate the PARI restriction sets the carry bit 
and returns error code in byte 52. 



.TITLE CDFN.MflC 

i + 

i .CDFN - This is an example in the use of the .CDFN re<iuest. The 
i example defines 32 new channels to reside in the body of the 
i program. 





.MCALL 


.CDFN. .PRINT. .EXIT 


START! 


.CDFN 


»AREA.»CHANL.«32. 




BCC 


1« 




.PRINT 


OBADCD 




.EXIT 




1$: 


.PRINT 
.EXIT 


»GOODCD 


AREA: 


.BLKU 


3 


CHANL: 


.BLKW 


5*32. 


BADCD: 


.ASCIZ 


/? .CDFN Failed ?/ 


GOODCD: 


.ASCIZ 


/.CDFN Successful/ 



iUse .CDFN to define 32. neu channels 

SBranch if successful 

iPrint failure message on console 

iExi t program 

SPrint success message 

iThen exit 

iEMT ArSument Block 
iSpace for neu channels 

iFai 1 ure message 
{Success messaSe 



.END 



START 



2.6 .CHAIN 



The .CHAIN request allows a background program to pass control directly 
to another background program without operator intervention. Since this 
process can be repeated, a long "chain" of programs can be strung together. 

The area in low memory from locations 500-507 contains the device name 
and file name (in Radix-50) to be chained to. The area from locations 
510-777 is used to pass information between the chained programs. 

Macro Call: .CHAIN 

Request Format: 

RO = 

Notes: 

1. Make no assumptions about which areas of memory remain intact 
across a .CHAIN. In general, only the resident monitor and locations 
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500-777 are preserved across a .CHAIN. In a .CHAIN to or from a 
virtual job, locations 500-777 are not preserved. 

I/O channels are left open across a .CHAIN for use by the new program. 
However, new I/O channels opened with a .CDFN request are not avail- 
able in this way. Since the monitor reverts to the original 16 channels 
during a .CHAIN, programs that leave files open across a .CHAIN 
should not use .CDFN. Furthermore, nonresident device handlers are 
released during a .CHAIN request and must be fetched again by the 
new program. Note that FORTRAN logical units do not stay open 
across a .CHAIN. 

An executing program determines whether it was chained to or RUN 
from the keyboard by examining bit 8 of the Job Status Word. The 
monitor sets this bit if the program was invoked with .CHAIN request. 
If the program was invoked with R or RUN command, this bit remains 
cleared. If bit 8 is set, the information in locations 500-777 is preserved 
from the program that issued the .CHAIN and is available for the cur- 
rently executing program to use. Again, locations 500-777 are not pre- 
served in a .CHAIN to or from a virtual job. 

An example of a calling and a called program is MACRO and CREF. 
MACRO places information in the chain area, locations 500-777, then 
chains to CREF. CREF tests bit 8 of the JSW. If it is clear, it means 
that CREF was invoked with the R or RUN command and the chain 
area does not contain useful information. CREF aborts itself immedi- 
ately. If bit 8 is set, it means that CREF was invoked with .CHAIN and 
the chain area contains information placed there by MACRO. In this 
case, CREF executes properly. 



Errors: 



.CHAIN is implemented by simulating the monitor RUN command 
and can produce any errors that RUN can produce. If an error occurs, 
the .CHAIN is abandoned and the keyboard monitor is entered. 

When using .CHAIN, be careful with initial stack placement. The 
linker normally defaults the initial stack to lOOO(octal); if caution is 
not observed, the stack can destroy chain data before it can be used. 



Example: 



.TITLE CHAIN. MAC 



.CHAIN - This example demonstrates the use of the .CHAIN 

. ,__.. » T* «u^j«c *n D..ndi<aM TTPRT.RAU' and passes it 

proDrctm i-eiucak* *v wmu^..^ v« ..--. — -. — .. — ■ 

a command line typed in at the console terminal. As an exercise 

write the prosram 'CTEST' - in it. cheoK to see if it was chained 

toi and if so. echo the data passed to iti otherwise print the 

message "Was not chained to". 



.MCALL 



.CHAIN. .TTYIN.. PRINT 



START! 



MOV 
MOV 


»500.R1 
»CHPTR.R2 


.REPT 
MOV 


4 
(R2)+.(R1)+ 


.ENDR 
.PRINT 


OPROMT 



iRl => Chain area 

iRZ => RAD50 ProSram Filespec 

iMoue the ProSram Filespec 

iinto the Chain area... 

i 

lAsk for the data to be passed 
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LOOP: 



CHPTR: 



PROMT: 



.TTYIN 

MOWB 

CMPB 

BNE 

CLRB 

.CHAIN 

.RAD50 

.RflDSO 

.RAD50 

.ASCII 

.END 



RO.(Rn + 
RO.alZ 
LOOP 
SRI 



iNou Set a "command" line 

ito pass to the chained prosram 

lin locations 510 and up. 

iLoop until line feed. 

iPut in a null byte as a terminator. 

iChain to the next prosram. 

iRADSO Fi le spec . . . 



/DK/ 

/CTEST / 

/SAV/ 

/Enter data to be passed to CTEST > /<Z00> 

START 



» IN CASE YOU DON'T HAVE TIME HERE'S AN EXAMPLE • 
» 'CTEST. MAC PROGRAM... # 





.TITLE 


CTEST. MAC 








.MCALL 


.PRINT, .EXIT 








JSN = aa 






iLocation of JSW 




CHAIN* = 


aoo 




iCHAIN bit in JSW 


CTEST: 


BIT 


•CHAIN*, @«JSW 




iWere ue chained to? 




BED 


1$ 




iBranoh if not 




.PRINT 


SCHAIND 




iSay ue were... 




Moy 


«510,R0 




iGet addr of start of data 




.PRINT 






iPrin t it out 




.EXIT 






iExit program 


1$: 


.PRINT 
.EXIT 


•NOCHN 




iSay we weren't chained to 
iThen exit 


CHAIND: 


.ASCIZ 


/CTEST was chained 


to 


- and here's the data passed. 


NOCHN: 


.ASCIZ 


/CTEST uias not chained 


to/ 




.END 


CTEST 







./ 



2.7 .CHCOPY (FB and XM Only) 

The .CHCOPY request opens a channel for input, logically connecting it to 
a file that is currently open by another job for either input or output. This 
request can be used by a foreground, background, or system job and must 
be issued before the first .READ or .WRITE request on that channel. 

.CHCOPY is valid only on files on disk (including diskette) or DECtape. 
However, no errors are detected by the system if another device is used. (To 
close a channel following use of .CHCOPY, use either the .CLOSE or 
.PURGE request.) 

Macro Call: .CHCOPY area,chan,ochan [,jobblk] 
where: 



area 
chan 
ochan 
jobblk 



is the address of a three-word EMT argument block 

is the channel the current job will use to read the data 

is the channel number of the other job's channel to be copied 

is a pointer to a three-word ASCII logical job name that 
represents a system job (see the RT-11 System Utilities 
Manual) 
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Request Format: 
RO -> area: 
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chan 



ochan 



jobblk 



Notes: 

1. If the other job's channel was opened with .ENTER in order to create a 
file, the copier's channel indicates a file that extends to the highest 
block that the creator of the file had written at the time the .CHCOPY 
was executed. 

2. A channel open on a non-file-structured device should not be copied, 
because intermixture of buffer requests can result. 

3. A program can write to a file (that is being created by the other job) on 
a copied channel just as it could if it were the creator. When the copier's 
channel is closed, however, no directory update takes place. 

4. Foreground and background jobs may optionally leave the jobblk argu- 
ment blank or set it to zero. This causes the job name to default to F if 
the background job issued the request, or to B if the foreground job 
issued the request. 



Errors: 

Code 


1 
Example: 



Explanation 

Other job does not exist, does not have enough channels de- 
fined, or does not have the specified channel {ochan) open. 

Channel (chan) already open. 



.CHCOPY - This is an example in the use of the .CHCOPY request. 
The example consists of two proarains; a Foreground Job uhich 
creates a file and sends a message to a BacKsround program 
whioh copies the FG channel and reads a record from the file. 
Both proarams must be assembled and linKed separately. 

.TITLE CHCOPF.MflC 
i + 

i This is the ForeSround proSram ... 
i - 

. MCALL . ENTER ,. PRINT . . SDflTW . . EXIT . . RCVDW . . CLOSE . . WRITW 



o I nix I r i 



ENTERR: 



.ENTER 
.WRITW 
BCS 
.SDATW 

.RCVDW 

.CLOSE 

.PRINT 

.EXIT 

.PRINT 

.EXIT 



Tii^uniiikj 1 n^ - y en I <il'3Uint;lli> uiuu'tx 

R5 .»0 i«FILE i«5 iCreate a 5 blooK file 

R5 1«0 isRECRD >»25B. .«a iWrite a record BG is interested in 



ENTERR 
R5,»BUFR.»2 

R5.sBUFR.8l 

«0 

8FEXIT 

»ERMSG 



iB ranch on error 

iSend messaSe with info to BG 

iOo some other processing 

iWhen it's time to exit. maKe sure 

!BG is done with the file 

iTell user we're exiting 

iEx i t the pro 3ram 

iPrint error message 

i then exit 
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FILE: 


.RAD50 


/DK OUFILE/ 


iFile 5Peo for .ENT 




,RflD50 


/TMP/ 






AREA: 


.BLKW 


5 




lEMT arsument block 


BUFR: 


.WORD 







iChannel « 




.MORD 


a 




iBIooK » 


RECRD: 


.BLKW 


25G. 




iFi 1 e reoo rd 


ERMSG: 


.ASCIZ 


/?Enter 


E r ro r?/ 


iErro r Message text 


FEXIT: 


.ASCIZ 
.END 


/FG Job 
STARTF 


exiting/ 


iExi t message 



.TITLE CHCOPB.MAC 
i + 

i This is the BacKSround prosram ... 
i - 

. MCALL . CHCOPY . . RC'DW . . READW ,. EXIT .. PRINT . ■ SDATW 



STARTS: 


MOV 


• AREA.R5 




;R5 => EMT ar9 blooK 






.RCVDW 


R5.»MSG,«2 




iWait for message from FG 






BCS 


1* 




i Bran oh if no FG 






.CHCOPY 


R5.»0,MSG + 2 




iChannel « is Ist word of 


message 




BCS 


2t 




iBranoh if FG channel not 


open 




.READW 


R5f«0,«BUFF,<t25B 


. (MSG+a iRead blocK which is 2n 


d word of msg 




BCS 

1 


3* 




JBranch.if read error 
iContinue processing... 






.SDATW 


R5.«MSG.«1 




iTell FG we're thru with 


file 




.PRINT 


•BEXIT 




iTell user we're thru 






.EXIT 






ithen exit p rosram 




1»: 


MOV 


SNOJOB.RO 




iRO => No FG error msS 






BR 


a* 




iBranoh to print mss 




2t: 


MOV 


sNOCHiRO 




iRO => FG ch not open ms3 






BR 


lit 




iB ranch . . . 




3$: 


MOV 


SRDERR.RO 




iRO => Read err msS 




4$: 


.PRINT 
.EXIT 






iPrint proper error msS 
ithen exit. 




AREA: 


.BLKW 


5 




iEMT argument blK 




MSG: 


.BLKW 


3 




iMessaSe buffer 




BUFF: 


.BLKW 


25B. 




iFile buffer 




BEXIT: 


.ASCIZ 


/Channel-Reoo rd 


COPY 


successful/ 




NOJOB: 


.ASCIZ 


/?No FG Job?/ 




iEr ro r messages .. . 




NOCH: 


.ASCIZ 


/?FG channel not 


open 


?/ 




RDERR: 


.ASCIZ 
.END 


/?Read Error?/ 
STARTB 









2.8 .CLOSE 



The .CLOSE request terminates activity on the specified channel and frees 
it for use in another operation. The handler for the associated device must 
be in memory if the file was created with a .ENTER programmed request. 

Macro Call: .CLOSE chan 

Request Format: 

RO = 



chan 



n .v-'X-ivwjxj xcqucDi/ oj^cv^iij' iiig a ^xiaiiucx buat xs ixui/ upcii lo igiiuicu. 

A file opened with .LOOKUP does not require any directory operations 
when a .CLOSE is issued, and the USR does not have to be in memory for 
such a .CLOSE. The USR is required if, while the channel is open, a request 
was issued that required directory operations. The USR is always required 
for special structured devices such as magtape. 

A .CLOSE is required on any channel opened with .ENTER if the associ- 
ated file is to become permanent. 
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NOTE 

Do not close channel 17(octal) if your program is overlaid, 
because overlays are read on that channel. 

A .CLOSE performed on a file opened with .ENTER causes the device direc- 
tory to be updated to make that file permanent. The first permanent file in 
the directory with the same name, if one exists, is deleted, provided that it 
is not protected. When a file that is opened with an .ENTER request is 
closed, its permanent length reflects the highest block written since it was 
entered. For example, if the highest block written is block number 0, the 
file is given a length of 1; if the file was never written, it is given a length 
of 0. If this length is less than the size of the area allocated at .ENTER 
time, the unused blocks are reclaimed as an empty area on the device. 

In magtape operations, the .CLOSE request causes the handler to write an 
ANSI EOFl label in software mode (using MM.SYS, MT.SYS, or MS.SYS) 
and to close the channel in hardware mode (using MMHD.SYS, 
MTHD.SYS, or MSHD.SYS). 

Errors: 

Code Explanation 

3 A protected file with the same name already exists on the 

device. The .CLOSE is performed anyway, resulting in two 
files with the same name on the device. 

.CLOSE does not return any other errors unless the .SERR request 
has been issued. If the device handler for the operation is not in 
memory, and the .CLOSE request requires updating of the device 
directory, a fatal monitor error is generated. 

Example: 

Refer to the examples for the .CSISPC and .WRITW requests, which 
show typical uses for .CLOSE. 

2.9 .CMKT (FB and XM; 8 J Monitor Special Feature) 

The .CMKT request causes one or more outstanding mark time requests to 
be canceled (see the .MRKT programmed request). The .CMKT request is a 
special feature in the SJ monitor, and is selected with the timer support 
during the system generation process. 

Macro Call: .CMKT area,id[,time] 

where: 

area is the address of a three- word EMT argument block 

id is a number that identifies the mark time request to be can- 

celed. If more than one mark time request has the same id, 
the request with the earliest expiration time is canceled. If 
id = 0, all non-system mark time requests (those in the 
range 1 to 176777) for the issuing job are canceled 
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time is the address of a two-word area in which the monitor re- 
turns the amount of time (clock ticks) remaining in the can- 
celed request. The first word contains the high-order time, the 
second contains the low-order. If an address of is specified, 
no value is returned. If id = 0, the time parameter is ig- 
nored and need not be indicated 

Request Format: 



RO -> area: 



23 



id 



time 



Notes: 

1. Canceling a mark time request frees the associated queue element. 

2. A mark time request can be converted into a timed wait by issuing a 
.CMKT followed by a .TWAIT, and by specifying the same time area. 

3. If the mark time request to be canceled has already expired and is 
waiting in the job's completion queue, .CMKT returns an error code of 
0. It does not remove the expired request from the completion queue. 
The completion routine will eventually be run. 

Errors: 

Code Explanation 

The id was not zero and a mark time request with the speci- 

fied identification number could not be found (implying that 
the request was never issued or that it has already expired). 

Example: 

Refer to the example for the .MRKT request. 

2.10 .CNTXSW (FB and XM Only) 

A context switch is an operation performed when a transition is made from 
running one job to running another. The .CNTXSW request is used to spec- 
ify locations to be included in a list when jobs are switched. Refer to the 
RT-11 Software Support Manual for further details. 

The system always saves the parameters it needs to uniquely identify and 
execute a job. These parameters include all registers and the following 
locations: 

34,36 Vector for TRAP instruction 
40-52 System Communication Area 

If an .SFPA request has been executed with a non-zero address, all floating- 
point registers and the floating-point status are also saved. 

It is possible that both jobs want to share the use of a particular location 
not included in normal context switch operations. For example, if a pro- 
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gram uses the lOT instruction to perform an internal user function (such as 
printing error messages), the program must set up the vector at 20 and 22 
to point to an internal lOT trap handling routine. If both foreground and 
background wish to use lOT, the lOT vector must always point to the 
proper location for the job that is executing. Including locations 20 and 22 
in the .CNTXSW list for both jobs before loading these locations accom- 
plishes this. This procedure is not necessary for jobs running under the XM 
monitor. In the XM monitor, both lOT and BPT vectors are automatically 
context switched. 

If .CNTXSW is issued more than once, only the latest list is used; the 
previous address list is discarded. Thus, all addresses to be switched must 
be included in one list. If the address (addr) is 0, no extra locations are 
switched. The list cannot be in an area into which the USR swaps, nor can 
it be modified while a job is running. 

In the XM monitor, the .CNTXSW request is ignored for virtual jobs, since 
they do not share memory with other jobs. For virtual jobs, the lOT, BPT, 
and TRAP vectors are simulated by the monitor. The virtual job sets up the 
vector in its own virtual space by any of the usual methods (such as a direct 
move or an .ASECT). When the monitor receives a synchronous trap from a 
virtual job that was caused by an lOT, BPT, or TRAP instruction, it checks 
for a valid trap vector and dispatches the trap to the user program in user 
mapping mode. An invalid trap vector address will abort the job with the 
following fatal error message: 

?MON-F-Inv SST (invalid synchronous system trap) 

Macro Call: .CNTXSW area,addr 



where: 



area is the address of a two-word EMT argument block 

addr is a pointer to a list of addresses terminated by a zero word. 
The addresses in the list must be even and be one of the 
following: 

a. in the range 2—476 

b. in the user job area 

c. in the I/O page (addresses 
160000-177776) 



Request Format: 




RO — » area: 


oo u 




addr 



Errors: 



Code Explanation 

One or more of the conditions specified by addr was violated. 
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Example: 



.TITLE CNTXSW.MftC 

•CNTXSW - This is an exawple in the use of the .CNTXSW request. 
In this exaiiiplei a .CNTXSM request is used to specify that location 20 
and ZZ (IQT vectors) and certain necessary EAE registers be context 
switched. This allows both Jobs to use lOT and the EAE simultaneously 
yet independently. 



.MCALL 



.CNTXSW. .PRINT. .EXIT 



START: 


.CNTXSW 


»AREA.aSWLIST 




BCC 


1$ 




.PRINT 


aADDERR 




.EXIT 




1«: 


.PRINT 
.EXIT 


SCNTOK 


SWLIST! 


.WORD 


ZO 




.WORD 


ZZ 




.WORD 


17730Z 




.WORD 


17730a 




.WORD 


177310 




.WORD 





AREA: 


.BLKW 


Z 


ADDERR: 


.ASCIZ 


/? .CNTXSW Ad 


CNTOK: 


■ASCIZ 


/.CNTXSW Succ 



ilssue the .CNTXSW request 

!Branch if successful 

SAddress error (should not occur) 

lEx i t the prosram 

iAcKnowled^e success with a message 

!then exit the program 

iAddresses to include in context switch 
i lOT & EAE uecto rs . . . 
iEAE registers... 



!Li St terminator !!! 



iEMT argument blocK 



.END 



START 



2=11 .CRAW (XM Only) 



The .CRAW request defines a virtual address window and optionally maps 
it into a physical memory region. Mapping occurs if you set the WS.MAP 
bit in the last word of the window definition block before you issue .CRAW. 
Since the window must start on a 4K word boundary, the program only has 
to specify which page address register to use and the window size in 32- 
word increments. If the new window overlaps previously defined windows, 
those windows are eliminated before the new window is created (except the 
static window reserved for a virtual program's base segment). 

Macro Call: .CRAW area.addr 



where: 



area is the address of a two-word EMT argument block 
addr is the address of the window definition block 

rru- ;_j „j-„i. 1 /iir ■\TC!Tna\ ^e -i-u^ — ; ] „ J„«— 44-;->», 

XllC WXIIUUW Bl/ClLUS WUIU \1M .i.-%tj X ij; Ul LllC WlllUUW UCillXlKl'LFll 

block may have one or more of the following bits set on return 
from the request: 

WS.CRW set if address window was successfully created 
WS.VNM set if one or more windows were unmapped to 

create and map this window 
WS.ELW set if one or more windows were eliminated 
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Request Format: 
RO —> area: 

Errors: 



36 



addr 



Code Explanation 

Window alignment error: the new window overlaps the 
static window for a virtual job. The window is too large or 
W.NAPR is greater than 7. 

1 An attempt was made to define more than seven windows in 
your program. You should eliminate a window first 
(.ELAW), or redefine your virtual address space into fewer 
windows. 

If the WS.MAP bit was set in the window definition block status word, the 
following errors can also occur: 



Code 

2 

4 

Example: 



Explanation 

An invalid region identifier was specified. 

The combination of the offset into the region and the size of 
the window to be mapped into the region is invalid. 



! + 

i This 
i The 
i memo 
i the 
i tech 



.TITLE XMCOPY 

is an exam.ple in the use of the RT-11 Extended Memory requests, 
prosram is a file copy with uerify utility that uses extended 
ry to implement flk transfer buffers. The example utilizes most of 
Extended Memory requests and demonstrates other proiramminS 
nisues useful in utilizins the requests. 



.NLIST 

.MCfiLL 

.MCflLL 

JSW 

J.yiRT 

ERRBYT 

APR 

APRl 

BUF 

BUFl 

CORSIZ 

PAGSIZ 

MRNID 

WRNIDl 



BEX 

.UNMAP 

.RDBBK 



. ELRG , . ELAW . . CRRG . . CRAW ,. MAP i . PRINT i . EXIT . . CLOSE 
. WDBBK i.TTYOUTi.WDBDF , . RDBDF , . CSIGEN . . READW . . WRI TW 
iJSW location 
iVirtual Job bit in JSW 
lError byte location 
iPAR/PDR for 1st uiindou 



2000 

52 

2 

a 

WDB+W.NBAS 

WDBl+W.NBAS 

4096. 

C0RSIZ/25G. 

WDB+W.NRID 

WDBl+W.NRID 



START: 



.ASECT 

= JSW 
.WORD J.yiRT 
.PSECT 

.WDBDF 
.RDBDF 

.CSIGEN »ENDCRE.«DEFLT,«0 
BCS START 



i " " 2nd 

iVirtual addr of Ist buffer 

i 2nd 

iSize of buffer in words 
iPaSe size in blocks 
tReSion ID addr of 1st reSion 
. „ „ .. .. 2nd 

iAssemble in the Virt Job Bit 

iMake this a "uirtual" Job 
iStart code nou 

iCreate Window Def Blk Symbols 
i " R e 3 i n " " " 

iGet filespecsi handlersi open files 
iBranch if error 
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INCB 


ERRNQ 




.CRRG 


•CAREA.BRDB 




BCC 


10$ 




JMP 


ERROR 


10$: 


Moy 


RDB iNRNID 




INCB 


ERRNO 




.CRAM 


»CAREA,«WDB 




BCC 


20$ 




JMP 


ERROR 


20»: 


INCB 


ERRNO 




.MAP 


<tCAREAi«MDB 




BCC 


30$ 




JMP 


ERROR 


30$: 


CLR 


Rl 




Moy 


«C0RSIZ,R2 




INCB 


ERRNO 


READ: 


.READM 


«RAREA.«3,BUFiR2.Rl 




BCC 


WRITE 




TSTB 


§«ERRBYT 




BEO 


PABS2 




JMP 


ERROR 


WRITE: 


MOU 


RCRZ 




.WRITW 


«RAREAi»0,BUF .R2.R1 




BCC 


ADDIT 




INCB 


ERRNO 




JMP 


ERROR 


ADDIT: 


ADD 


•PAGSIZ.Rl 




BR 


READ 


PfiSS2: 


INCB 


ERRNO 




.CRRG 


»CflREA.«RDBl 




BCC 


35$ 




JMP 


ERROR 


35$: 


Moy 


RDBl .WRNIDl 



ERR = 1« 

Create a resion 

Branch if successful 

Report error (JMP due to ranSe!) 

Moue resion id to Window Def Blk 

ERR = 2x 

Create window <• < 

Branch if no error 

Report error... 

ERR = 3x 

Explicitly map window... 

Branch if no error 

Report error 

Rl = RTU BlocK » for I/O 

R2 = « of words to read 

ERR = ax 

Tr/ to read flK worth of blocKs 

B ranch if no error 

EOF? 

B ranch if yes 

Must be hard error* report it 

R2 = size of buffer Just read 

Write out the buffer 

Branch if no error 

ERR = 5x 

Report error 

Adjust block * 

Then So Set another buffer 

ERR = Bx 

Create a resion 

Branch if no error 

Report error 

Get resion id to window def blk 



!» EXAMPLE USING THE .CRAW REQUEST DOING • 
!* IMPLIED .MAP REQUEST. ♦ 





INCB 


ERRNO 




.CRAW 


»CAREAi«WDBI 




BCC 


VERIFY 




JMP 


ERROR 


yERIFY:. : 


INCB 


ERRNO 




CLR 


Rl 


GETBLK: 


MOV 


•CORSIZ.RZ 




.READW 


»RAREA.«3,BUF1 .R2,R1 




BCC 


ao$ 




TSTB 


e»ERRBYT 




BEO 


ENDIT 




JMP 


ERROR 


ao$: 


MOV 


R0.R2 




.READW 


«RAREA,itO.BUF.R2.Rl 




BCC 


50$ 




INCB 


ERRNO 




JMP 


ERROR 


50$: 


MOV 


BUF.Ra 




MOV 


BUFl .R3 


70$: 


CMP 


(Ra)+,(R3)+ 




BNE 


ERRDAT 




DEC 


R2 




BNE 


70$ 




ADD 


SPAGSIZ.RI 




BR 


GETBLK 


ENDIT: 


.PRINT 


•ENDPRG 


XCLOS: 


.CLOSE 


»0 




.UNMAP 


«CAREA.«WDB 




.ELAW 


«CAREAf«WDB 




.ELRG 


»CAREA,«RDB 




.ELRG 


»CAREA.»RDB1 




.EXIT 





ERR = 7x 

Create window usins implied .MAP 

B ranch if no error 

Repo rt error 

ERR = 8x 

Rl = RTll block « aiain 

R2 = ak buffer size 

Try to Set ^K worth of input file 

Branch if no error 

EOF? 

Branch if yes 

Repo rt hard error 

R2 = size of buffer read 

Try to Set same size from output file 

B ranch if no error 

ERR = 9x 

Report error 

Get output buffer address 

Get input buffer address 

Verify that data is the same 

It's not I report error 

Are we finished? 

Branch if we aren't 

Adjust block « for paSe size 

Go Set another buffer pair 

iAnnounoe we're finished 

SClose output file 

iExplicitly unmap 1st window 

iExplioitly eliminate 1st window 

iEliminate Ist resion 

• Unmap lel iminate 2nd window & resion 

!Exit prosram 
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ERROR: 


MOVB 

ADD 

MOVB 

.PRINT 

BR 


0oerrbyt.ro 

a'O.RO 
RO.ERRNO+1 
»ERR 
XCLOS 








iMaKe error byte code Znd diait 

lof error code... 

iPut it in error message 

iPrint it... 

!Go close output file 


ERRDfiT: 


.PRINT 
BR 


«ERRBUF 
XCLOS 








iReport verify failed... 
iGo close output file. 


RDB: 


.RDBBK 


C0RSIZ/3Z. 








i.RDDBK defines ReSion Def BIK 


MDB: 


.WDBBK 


APR.C0RSIZ/3Z. 








i.WDDBK defines Windou Def BIK 


RDBl: 


.RDBBK 


CORSIZ/32. 








iDefine 2nd reiion same uay 


MDBl: 


.MDBBK 


APRl .CORSIZ/32. 


.0 


,0 


.CORSIZ/32. .WS. MAP i and 2nd Windou 














i(but uith mappins status set!) 


CAREA: 


.BLKW 


2 








iEMT argument blocks 


RAREA: 


.BLKW 


6 










DEFLTi 


.WORD 


lO (0 lO 








iNo default extensions 


ENDPRG: 


.ASCIZ 


/ • End of XM E 


Kamp 


e 


Proiram */ 


ERR: 


.ASCII 


/?XM Request or 


I 


-0 


E 


r ro r » / 


ERRNO: 


.ASCIZ 


/OO/ 










ERRBUF: 


. ASCIZ 


/?Data Verification 


E 


rro r?/ 


ENDCRE 


= * 










iFor CSIGEN - XM handlers loaded 



.END 



START 



2.12 .CRRG (XM Only) 



The .CRRG request directs the monitor to allocate a dynamic region in 
physical memory for use by the current requesting program. 



Macro Call: 
where: 

area 
addr 



.CRRG area,addr 



is the address of a two-word EMT argument block 

is the address of the region definition block for the region to 
be created 



Request Format: 
RO 



area: 



36 



addr 



Errors: 



Code 

6 



10 



Explanation 

No region control blocks are available. You eliminate a re- 
gion to obtain a region control block (.ELRG), or you can 
redefine your physical address space into fewer regions. 

A region of the requested size cannot be created because not 
enough memory is available. The size of the largest avail- 
able region is returned in RO. 

An invalid region size was specified. A value of 0, or a value 
greater than the available amount of contiguous extended 
memory, is invalid. 



Example: 

Refer to example for the .CRAW request. 
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2.13 .CSIGEN 

The .CSIGEN request calls the Command String Interpreter (CSI) in gen- 
eral mode to process a standard RT-11 command string. In general mode, 
file .LOOKUP and .ENTER requests as well as handler .FETCH requests 
are performed. 

The .CSIGEN request accepts a command string of the form dev:output- 
filespec = dev:input-filespecl options, and the following operations occur: 

1. The handlers for devices specified in the command line are fetched. 

2. .LOOKUP and/or .ENTER requests on the files are performed. 

3. The option information is placed on the stack. See the end of this sec- 
tion for a description of the way option information is passed. Note that 
this call always puts at least one word of information on the stack. 

When called in general mode, the CSI closes channels through lO(octal). 

.CSIGEN loads all necessary handlers and opens the files as specified. The 
area specified for the device handlers must be large enough to hold all the 
necessary handlers simultaneously. If the device handlers exceed the area 
available, your program can be destroyed. (The system, however, is pro- 
tected.) 

The three possible output files are assigned to channels 0, 1, and 2, and the 
six possible input files are assigned to channels 3 through lO(octal). A null 
specification causes the associated channel to remain inactive. For exam- 
ple, the following string 

*tLP:=Fl .F2 

causes channel to be inactive since the first specification is null. Channel 
1 is associated with the line printer, and channel 2 is inactive. Channels 3 
and 4 are associated with two files on DK:, while channels 5 through 10 are 
inactive. Your program can determine whether a channel is inactive by 
issuing a .WAIT request on the associated channel, which returns an error 
if the channel is not open. 

Macro Call: .CSIGEN devspc,defext[,cstrng][,linbuf] 

where: 

devspc is the address of the memory area where the device han- 
dlers (if any) are to be loaded 

defext is the address of a four-word block that contains the Ra- 
dix-50 default file types. These file types are used when a 
file is specified without a file type (see Note 1) 

cstrng is the address of the ASCIZ command string or a if input 
is to come from the console terminal. (In an FB or XM envi- 
ronment, if the input is from the console terminal, an .UN- 
LOCK of the USR is automatically performed while the 
string is being read, even if the USR is locked at the time.) 

2-18 Programmed Request Description and Examples 



If the string is in memory, it must not contain a ® © (octal 
15 and 12), and must terminate with a zero byte. If the 
cstrng field is blank, input is automatically taken from the 
console terminal. This string, whether in memory or en- 
tered at the console, must obey all the rules for a standard 
RT-11 command string 

linbuf is the storage address of the original command string. This 
is a user-supplied area, 81 decimal bytes in length. The 
command string is terminated with a zero byte. If this argu- 
ment is omitted, the input command string is not copied to 
user memory 

On return, RO points to the first available location above the handlers, the 
stack contains the option information, and all the specified files have been 
opened. 

Note: 

1. The four- word block pointed to by defext is arranged as: 

Word 1: default file type for all input channels (3-10) 

Words 2,3,4: default file types for output channels 0, 1, and 2, 
respectively 

If there is no default for a particular channel, the associated word must 
contain 0. All file types are expressed in Radix-50. For example, the 
following block can be used to set up default file types for a macro 
assembler: 

DEFEXT: .RAD50 "MAC" 

,RAD50 "OBJ" 

.RAD50 "LST" 

.WORD 

In the command string: 

»DT0:ALPHA.DTl!BETA=DT2!lNPUT 

the default file type for input is MAC; for output, OBJ and LST. The 
following cases are valid: 

*DTO:OUTPUT= 
*DT2! INPUT 

In other words, the equal sign is not necessary if only input files are 
specified. 

2. An optional argument (linbuf) is available in the .CSIGEN format that 
provides the user with an area to receive the original input string. The 
input string is returned as an ASCIZ string and can be printed through 
a .PRINT request. 

3. The .CSIGEN request automatically takes its input line from an indi- 
rect command file if console terminal input is specified (cstrng = #0) 
and the program issuing the .CSIGEN is invoked through an indirect 
command file. 
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Errors: 



If CSI errors occur and input was from the console terminal, an error 
message describing the fault is printed on the terminal and the CSI 
retries the command. If the input was from a string, the carry bit is 
set and byte 52 contains the error code. In either case, the options and 
option-count are purged from the stack. These errors are: 

Code Explanation 

Invalid command (such as bad separators, invalid file 
names, and commands that are too long). 

1 A device specified is not found in the system tables. 

2 A protected file of the same name already exists. A new file 
was not opened. 

3 Device full. 



4 An input file was not found in a .LOOKUP. 



Example: 



.TITLE 



CSIGEN.MflC 



.CSIGEN - This is an example in the use of the .CSIGEN request. 

The example is a single file copy program. The file specs are 

input from the console terminal! and the input & output files opened 

uia the Seneral mode of the CSI. The file is copied usinS synchronous 

I/Oi and the output file is made permanent uia the .CLOSE request. 



Error Byte Location 





.MCALL 


.CSIGENi.READNi. 




ERRBYT=52 


START: 


.CSIGEN 


8DSPACEi»DEXT 




MOV 


RO.BUFF 




CLR 


INBLK 




MOV 


«LIST,R5 


READ: 


.READU 


R5.»3.BUFF.aZ5G. 




BCC 


2* 




TSTB 


@»ERRBYT 




BEQ 


EOF 




MOV 


OINERR.RO 


1$: 


.PRINT 






CLR 


RO 




.EXIT 




2$: 


.NRITM 


R5.»0.BUFF.»Z5G. 




BCC 


NOERR 




MOV 


aWTERR.RO 




BR 


1$ 


NQERR: 


INC 


INBLK 




BR 


READ 


EOF: 


.CLOSE 


»0 




.CLOSE 


83 




.SRESET 






.EXIT 




DEXT: 


.MORD 


(0 lO lO 


BUFF: 


.WORD 





INBLK: 


.MORD 





LIST: 


.BLKW 


5 



iINBLK 



(INBLK 



Get strinS from terminal 

RO has first free location 

Input blooK » 

EMT ArSument list 

Read a blocK on Channel 3 

B ranch if no errors 

EOF error ? 

Yes. . . 

RO => Read Error Message 

Print the messase 

Clear RO for hard exit 

Exit the prosram 

Mrite the blocK Just read 

Branch if no error 

RO => Write error messaSe 

Branch to output the message 

Otheruiisei increment block » 

and loop to read next blooK 

End-of -Fi 1 e . . .CLose output channel 

And input channel 

Release handler(s) from memory 

Exit the p ro^ram 

No default extensions 

I/O Buffer start 

Relative blocK to read/write 

EMT argument list 



INERR: 



.ASCIZ 



/? Input error ?/ 
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WTERR: 



.ASCIZ /? Output error ?/ 
.EVEN 



DSPACE 



iHandlerfs) can be loaded starting here 



.END 



START 



2.13.1 Passing Option Information 

In both general and special modes of the CSI, options and their associated 
values are returned on the stack. A CSI option is a slash (/) followed by any 
character. The CSI does not restrict the option to printing characters, al- 
though you should use printing characters to avoid confusion. The option 
can be followed by a value, which is indicated by a : separator. The : separa- 
tor is followed by an octal number, a decimal number, or by one to three 
alphanumeric characters, the first of which must be alphabetic. Decimal 
values are indicated by terminating the number with a decimal point 
(/N:14.). If no decimal point is present, the number is assumed to be octal. 
Options can be associated with files. For example, the command string 

*DK:F00/A»DT4:FILE.DBJ/A: 100 



has two A options. The first is associated with the input file DK:FOO. The 
second is associated with the input file DT4:FILE.0BJ and has a value of 
lOO(octal). The format of the stack output of the CSI for options is as fol- 
lows: 



Word # 

1 
(top of 
stack) 



Value Meaning 

N Number of options found in command 

string. If N=0, no options were found. 



Option character Even byte = 
and file number 

Bits 8-14 = 



seven-bit ASCII option 
character 

number (0-10) of the file 
with which the option is 
associated 



Option value 
or next option 



Bit 15 = 1 if the option had a 

value 

= if the option had no 
value 

If bit 15 of word 2 is set, word 3 contains 
the option value. If bit 15 is not set, word 3 
contains the next option character and file 
number, if any. 



For example, if the input line to the CSI is 

»FILE/B!20. >FILZ/E=DT3:INPUT/X:SY:Z0 
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on return, the stack is: 
Stack Pointer —> 



101530 

20 

101530 

075250 

505 

100102 

24 



Three options appeared (X option has two 

values and is treated as two options). 

Last option = X; with file 3, has a value. 

Value of option X = 20(octal). 

Next option =X; with file 3, has a value. 

Next value of option X = RAD50 code for 

SY. 

Next option = E; associated with file 1, no 

value. 

Option = B; associated with file and has 

a value of 24. 

(octal). 



As an extended example, assume the following string was input for the CSI 
in general mode: 

*FILE[8. ] .LP: .SY : F ILE2C20 . ] = PC; .DTI: INI /B tDT2 : I N2/M : 7 



Assume also that the default file type block is: 



EFEXT: 


.RAD50 


'MAC 




.RAD50 


'DPI ' 




.RAD50 


'0P2' 




.RAD50 


'0P3' 



ilNPUT FILE TYPE 
iFIRST OUTPUT FILE TYPE 
JSECOND OUTPUT FILE TYPE 
JTHIRD OUTPUT FILE TYPE 



The results of the above CSI call are as follows: 

1. An eight-block file named FILE.OPl is entered on channel on device 
DK:; channel 1 is open for output to the device LP:; a 20-block file 
named FILE2.0P3 is entered on the system device on channel 2. 

2. Channel 3 is open for input from device PC:; channel 4 is open for input 
from a file INl.MAC on device DTI:; channel 5 is open for input from 
IN2.MAC on device DT2:. 

3. The stack contains options and values as follows: 

Contents Explanation 

2 Two options found in string. 

102515 Second option is M, associated with channel 5; has a value. 

7 Numeric value is 7 (octal). 

2102 Option is B, associated with channel 4; has no value. 

If the CSI were called in special mode, the stack would be the same as for 
the general mode call, and the descriptor table would contain: 



OUTSPC; 


15270 


; .RAD50 




'DK ' 






233B4 


!.RAD50 




'FIL' 






17500 


i .RAD50 




'E' 






B0137 


5.RAD50 




'DPI ' 






10 


iLENGTH 


OF 


8 BLOCKS 


(DECIMAL) 




4GB00 


i .RAD50 




'LP' 
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NO NAME OR LENGTH SPEC 


'J 


75250 


.RAD50 


SY' 


233Ba 


.RAD50 


FIL' 


22100 


.RAD50 


E2' 


BOiai 


.RAD50 


0P3' 


2n 


LENGTH OF 


20 (DECIMAL) 


B2170 


.RAD50 


PC 






NO NAME SPECIFIED 



1B077 


.RAD50 


DTI 




35217 


.RAD50 


INI 







.RAD50 






50553 


.RAD50 


MAC 




ISIOO 


.RAD50 


DT2 




35220 


.RAD50 


IN2 







.RAD50 






50553 


.RAD50 


MAC 














(12 wore zero words are returned) 



Keyboard error messages that can occur when input is from the console 
keyboard include: 



Message 

?CSI-F-Invalid command 
?CSI-F-file not found 
?CSI-F-Device full 
?CSI-F-Invalid device 
?CSI-F-Protected file 



Meaning 

Syntax error. 
Input file was not found. 
Output file does not fit. 
Device specified does not exist. 
Output file specified already 
exists and is protected. 



Notes: 



In many cases, your program does not need to process options in CSI 
calls. However, you could inadvertently enter options at the console. In 
this case, it is wise to save the value of the stack pointer before the call 
to the CSI, and restore it after the call, so that no extraneous values are 
left on the stack. Note that even a command string with no options 
causes a word to be pushed onto the stack. This word indicates the 
number of options to follow. 



2. Under an FB monitor; calls to the CS! that require console terminal 
input always do an implicit .UNLOCK of the USR while the string is 
being gathered. This should be kept in mind when using .LOCK calls. 



2.14 .CSfSPC 



The .CSISPC request calls the Command String Interpreter in special mode 
to parse the command string and return file descriptors and options to the 
program. In this mode, the CSI does not perform any .CLOSE, .ENTER, 
.LOOKUP, or handler .FETCH requests. 
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Options and their associated values are returned on the stack. The optional 
argument (linbuf) can provide your program with the original command 
string. 

.CSISPC automatically takes its input line from an indirect command file if 
console terminal input is specified icstrng - #0) and the program issuing 
the .CSISPC is invoked through an indirect command file. 

Note that in a foreground/background environment, calling the CSI per- 
forms a temporary and implicit .UNLOCK while the command line is being 
read. 

Macro Call: .CSISPC outspc,defext[,cstrng][,linbufl 
where: 

outspc is the address of the 3 9- word block to contain the file 
descriptors produced by .CSISPC. This area can overlay the 
space allocated to cstrng, if desired 

defext is the address of a four-word block that contains the Ra- 
dix-50 default file types. These file types are used when a 
file is specified without a file type 

cstrng is the address of the ASCIZ input string or a #0 if input is 
to come from the console terminal. If the string is in mem- 
ory, it must not contain a (HD © (octal 15 and 12), and must 
terminate with a zero byte. U cstrng is blank, input is auto- 
matically taken from the console terminal or indirect file, if 
one is active 

linbuf is the storage address of the original command string. This 
is a user-specified area, 81 bytes in length. The command 
string is terminated with a zero byte instead of ® © (octal 
15 and 12) 

Notes: 

1. The file description consists of 39 words, comprising nine file descriptor 
blocks (five words for each of three possible output files; four words for 
each of six possible input files), which correspond to the nine possible 
files (three output, six input). If any of the nine possible file names are 
not specified, the corresponding descriptor block is filled with zeroes. 

2. The five-word blocks hold four words of Radix-50 representing 
dev: file. type, and one word representing the size specification given in 
the string. (A size specification is a decimal number enclosed in square 
brackets ([ ]) that follows the output file descriptor.) For example: 

*DT3:LIST.MAC[15]=PC! 

Using special mode, the CSI returns in the first five-word slot: 

16101 Radix-50 for DT3 

46173 Radix-50 for LIS 

76400 Radix-50 for T 

50553 Radix-50 for MAC 

00017 Octal value of size request 
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In the fourth slot (starting at an offset of 36 bytes [octal] into outspc), 
the CSI returns: 

62170 Radix-50 for PC 

No file name 
specified 

No file type given 

Since this is an input file, only four words are returned. 

Errors: 

Errors are the same as in general mode except that invalid device 
specifications are checked only for output file specifications with null 
file names. Since .LOOKUP and .ENTER requests are not done, the 
valid error codes are: 




1 

Example: 



Code Explanation 

Invalid command line. 
Invalid device. 



•TITLE CSISPC.MflC 

h 

• CSISPC - This is an example in the use of the .CSISPC re-iuest. 
The example uses the "special" mode of CSI to Set an input 
specification from the console terminal) then uses the .DSTflTUS 
request to determine if the output deuice's handler is loaded! 
if not I a .FETCH request is issued to load the handler into 
memory. Finally a .DELETE request is issued to delete the specified 
file. 





.MCALL 




•DSTATUS. •PRINT. •£> 


START: 


MOV SP. 


R5 






•CSISPC 




aOUTSP.sDEFEXT 




MOV R5. 


SP 






•DSTAT 




aSTAT.sOUTSP 




TST 




STAT+a 




BNE 




Z« 




•FETCH 




aHANLOD.»INSPEC 




BCC 




2* 




•PRINT 




SFEFAIL 




■ EXIT 






2«: 


•DELETE 




8AREA.«0iSINSPEC 




BCC 




3« 




•PRINT 




9N0FIL 




BR 




START 


3*: 


•PRINT 




»FILDEL 




• EXIT 






AREA: 


• BLKW 




2 


STAT: 


• BLKU 




a 


DEFEXT: 


• MORD 




(0 >0 (0 


FEFAIL: 


•ASCIZ 




/?^FETCH Failed?/ 


NOFIL: 


•ASCIZ 




/?File Not Found?/ 


FILDEL: 


•ASCIZ 
• EVEN 




/IFile Deleted!/ 


OUTSP: 


•BLKW 5*3 




INSPEC: 


•BLKU a«6 




HANLQD: 


•BLKU 1 







iSaue current stack pointer 

iUse •CSISPC to Set output spbc 

iRestore SP to clear any CSI options 

iChecK on the output deuice 

i(CSISPC catches illeSal devices!) 

iSee if the device is resident 

iBranoh if already loaded 

ilt's not loaded ••• b rin S it into memory 

iBranch if successful 

iFetch fai led ••• print error messaSe 

ithen exit proSram 

iNou delete the file 

iBranch if successful 

iPrint error messaSe 

iThen try aSain 

iAoKnouledse successful deletion 

•then exit program 

;EMT Argument block 
iBlcck for status 
;No default extensions 
iFetch failed messase 
iFi le not found 
iDelete acknouledsment 
iFix boundary 

SOutPut specs 90 here 

i Input specs so he re 

iHandlers besin loadins here (if necessary) 



• END 



START 



Programmed Request Description and Examples 2-25 



2.15 .CSTAT 

This request furnishes you with information about a channel. 

Macro Call: .CSTAT area,chan,addr 

where: 

area is the address of a two-word EMT argument block 

chan is the number of the channel about which information is de- 
sired 

addr is the address of a six-word block to contain the status 

Request Format: 

RO — > area: 



27 chan 



addr 



Notes: 

The six words passed back to the user correspond to the following six points 
of information: 

1. Channel status word (see the RT-11 Software Support Manual for de- 
tails) 

2. Starting block number of file (0 if sequential-access device, or if channel 
was opened with a non-file-structured .LOOKUP or .ENTER) 

3. Length of file (0 if non-iile-structured device, or if channel was opened 
with a non-file-structured .LOOKUP or .ENTER) 

4. Highest relative block written since file was opened (no information if 
non-file-structured device). This word is maintained by the 
.WRITE/.WRITC/.WRITW requests 

5. Unit number of device with which this channel is associated 

6. Radix-50 of the device name with which the channel is associated (this 
is a physical device name, unaffected by any user name assignment in 
effect). 

Errors: 

Code Explanation 

The channel is not open. 
Example: 

.TITLE CSTflT.MfiC 
! + 

! .CSTflT - This is an example in the use of the .CSTAT request. 
i In this examplei iCSTAT is used to determine the iRADSO 
i representation of the deuice uith which the channel is associated. 
i - 

.MCALL . CSTAT.. CSI GEN.. PR INT.. EX IT 



START! 


Moy 


SP. R5 


iSaue current staoK pointer 






.CSIGEN 


aDEVSDC.«OEFEXT 


iQpen files 






Moy 


R5. SP 


iRestore SP to clear any CSI 


options 




.CSTAT 


«AREA,«0.»ADDR 


iGet the status 






BCS 


NDCHAN 


.Channel not open 






Mcy 


»ADDR+10.R5 


.Point to unit » 
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MOV 


(R5)+.R0 






iUnit « to RO 




ADD 


(PC) + .RO 






iMaKe it RfiDSO 




.RAD50 


/ 0/ 










ADD 


(R5) .RO 






iGet deyice name 




MOV 


RO.DEVNAM 






i'DEVNAM' has RfiDSO deuice name 




.EXIT 








iExit the proSram 


NOCHAN: 


.PRINT 
.EXIT 


»MSG 






iPrint error tnessaSe 
ithen exit prosram 


MSG: 


.ASCIZ 
.EVEN 


/?No Output 


Fi 


le?/ 


iErro r messaSe 
iFix boundary 


AREA: 


.BLKM 


5 






;EMT ari list 


ADDR: 


.BLKW 


6 






iArea for ohannel status 


DEVNAM! 


.WORD 









'.Storage for device name 


DEFEXT: 


.MORD 


0.0,0.0 






iNo default extensions 


DEySDC=. 










■Start C5I tables here... 



.END 



START 



2.16 .CTIMfO (Device Handler Only) 

The .CTIMIO macro cancels the device time-out request in the handler 
interrupt service section. It is used when an interrupt occurs to disable the 
completion routine (see .TIMIO). 

If the time interval has already elapsed and the device has, therefore, timed 
out, the .CTIMIO request fails. The completion routine has already been 
placed in the queue. The .CTIMIO call returns with the C bit set when it 
fails because the completion routine was already queued. 

The device time-out feature must have been selected during the system 
generation process. 

Macro Call: .CTIMIO tbk 

where: 

tbk is the address of the seven-word timer block shown in Table 
2-1 

Table 2-1: Timer Block Format 



Offset FiUed in By 



Contents 






.TIMIO 


2 


.TIMIO 


4 


monitor 


6 


user 



High-order time word (expressed in ticks). 

Low-order time word (expressed in ticks). 

Link to next queue element; indicates none. 

Owner's job number; for background job, MAXJOB for fore- 
ground job, and job priority *2 for system jobs. MAXJOB is 
equal to (the number of jobs in the system * 2)— 2. The job 
number for the foreground job is 2 in a system without system 
jobs, and 16 for a system with system jobs. The job number is 
set from the queue element. 

Sequence number of timer request. The valid range of sequence 
numbers is from 177000 to 177377. 



10 

12 
14 



user 

monitor 
user 



Address of the completion routine to execute if timeout occurs. 
The monitor zeroes this word when it calls the completion 
routine, indicating that the timer block is available for reuse. 
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The .CTIMIO macro expands as follows: 



.CTIMIO tbk 



JSR 

.UORD 

.MORD 



R5»i*TIMIT 
tbK - . 
1 



.POINTER AT END OF HANDLER 
iCODE FOR .CTIMIO 



Example: 

Refer to the example for the .TIMIO request. 



2.17 .DATE 



This request returns the current date information from the system date 
word in RO. The date word returned is in the following format: 

BIT: 15 14 13 ... 10 9 ... 5 4 ... 

MONTH DAY YEAR 

The year value in bits 4-0 is the actual year minus 1972. The day in bits 9 
to 5 is a number from 1 to the length of the month. The month in bits 13 to 
10 is a number from 1 to 12. 

NOTE 

RT-11 support of month and year rollover is a system gener- 
ation special feature; otherwise, the keyboard monitor DATE 
command must be issued to change the month and year. 

Macro Call: .DATE 

Request Format: 

RO - 

Errors: 

No errors are returned. A zero result in RO indicates that the user has 
not entered a date. 



12 







Example: 



.TITLE DATE.MAC 



.DATE - Thi5 is an example in the use of the .DATE resuesti 
This example may be assembled separately and linKed with 
user written proSrams 



INPUT: 
OUTPUT! 



none 

RO = MONTH (1-lZ) 

Rl = DAY (1-31) 

RZ = YEAR (Last two disits) 
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ERRORS: 



RO = if no date entered 



.MCftLL 



.DATE 



DATE: 



1$: 



.DATE 




MOU 


R0.R2 


BEg 


1* 


BIC 


«'C37iR2 


ADD 


«72. ,R2 


Moy 


RO.Rl 


ABL 


Rl 


ASL 


Rl 


ASL 


Rl 


SUAB 


Rl 


BIC 


a-C37,Rl 


SWAB 


RO 


ASR 


RO 


ASR 


RO 


BIC 


»-C17,R0 


RETURN 





iGet date in RO via 4DATE request 

iCopy RO 

ilf zeroi no date uias entered 

•Clear all but year bits 

»MaKe it current year 

iCopy date uord asain 

iGet day bits 

ion a byte boundary><< 

i 

iPut day bits in lou order byte 

iClear all but day bits 

iPut Month bits in lou byte 

iRi Sht adjust 

inionth bi ts > • 1 

iCIear all but month bits 

iReturn to oallinJ prosram 



.END 



dL m 10 B^^^Blaga^i I ILu 



The .DELETE request deletes a named file from an indicated device. The 
.DELETE request is invalid for magtapes. The .SERR programmed request 
can be used to allow the program to process any errors. 

Macro Call: .DELETE area,chan,dblk[,seqnum] 

where: 

area is the address of a three-word EMT argument block 

chan is the device channel number in the range 0-376(octal) 

dblk is the address of a four-word Radix-50 descriptor of the 

file to be deleted 

seqnum file number for cassette operations: if this argument is 
blank, a value of is assumed 

Request Format: 

RO -^ area: 



chan 



dblk 



seqnum 



Notes: 

The channel specified in the .DELETE request must not be open when the 
request is made, or an error will occur. The file is deleted from the device, 
and an empty (UNUSED) entry of the same size is put in its place. A 
.DELETE issued to a non-file-structured device is ignored. .DELETE re- 
quires that the handler to be used be in memory at the time the request is 
made. When the .DELETE is complete, the specified channel is left inac- 
tive. 
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Errors: 

Code 

1 
2 
3 

Example: 



Explanation 

Channel is active. 

File was not found in the device directory. 

Invalid operation. 

The file is protected and cannot be deleted. 



.TITLE DELETE. MAC 

.DELETE - This is an example in the use of the .DELETE request. 
The example uses the "special" mode of CSI to Set an input 
specification from the console terminali then uses the .DSTflTUS 
request to determine if the output deuice's handler is loaded! 
if not I a .FETCH re-iuest is issued to load the handler into 
memory. Finally a .DELETE resuest is issued to delete the specified 
file. 



.MCALL 



.DSTflTUS .. PRINT .. EXIT . .FETCH . .CSISPC . .DELETE 



START: 


Moy 


SP, R5 




.CSISPC 


»aUTSP.»DEFEXT 




Moy 


R5. SP 




.DSTAT 


•STAT.«OUTSP 




TST 


STAT+a 




BNE 


2* 




.FETCH 


sHANLOD iSINSPEC 




BCC 


2» 




.PRINT 


•FEFfllL 




.EXIT 




2%: 


.DELETE 


«AREA,»0.»INSPEC 




BCC 


3» 




.PRINT 


SNOFIL 




BR 


START 


3$: 


.PRINT 


sFILDEL 




.EXIT 




AREA: 


.BLKN 


2 


STAT: 


.BLKW 


a 


DEFEXT: 


.MDRD 


0.0.0,0 


FEFAIL: 


.ASCIZ 


/?. FETCH Failed?/ 


NOFIL: 


.ASCIZ 


/?File Not Found?/ 


FILDEL: 


.ASCIZ 
.EVEN 


/IFile Deleted!/ 


OUTSP: 


.BLKW 5*3 




INSPEC: 


.BLKW a»s 




HANLOD: 


.BLKW 1 






.END 


START 



iSaue current stacR pointer 

iUse .CSISPC to Set output spec 

iRestore SP to clear any CSI options 

iChecK on the output device 

i(CSISPC catches illesal deuices!) 

iSee if the deuioe is resident 

iBranch if already loaded 

ilt's not loaded ... b rins it into memory 

iBranch if successful 

iFetoh failed. ..print error message 

ithen exit pro 3ram 

iNow delete the file 

iBranch if successful 

iPrint error messase 

iThen try aSain 

!AcKnowled3e successful deletion 

ithen exit pro3 ram 

iEMT Argument blocK 

iBlocK for status 

iNo default extensions 

iFetch failed messaSe 
iFi le not found 
iDelete acKnoul ed 9men t 
iFix boundary 

lOutPut specs 30 here 

ilnput specs 3o here 

iHandlers be3in loadinS here (if necessary) 



2.19 .DEVICE (FB and XM Only) 

This request allows your program to load device registers with any neces- 
sary values when the program is terminated. You set up the list of ad- 
dresses with the specified values. Upon issuing an .EXIT request or a 
CTRL/C from the terminal, this list is picked up by the system and the 
designated addresses are loaded with the corresponding values. This func- 
tion is primarily designed to allow your program to turn off a device's 
interrupt enable bit when the program servicing the device terminates. 
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Successive calls to .DEVICE are allowed when you need to link requested 
tables. When the job is terminated for any reason, the list is scanned once. 
At that point, the monitor disables the feature until another .DEVICE call 
is executed. Thus, background programs that are reenterable should in- 
clude .DEVICE as a part of the reenter code. 

The .DEVICE request is ignored when it is issued by a virtual job running 
under the XM monitor. 

Macro Call: .DEVICE area,addr[,link] 

where: 

area is the address of a two-word EMT argument block 

addr is the address of a list of two- word elements, each composed of 
a one-word address and a one-word value to be put at that 
address. If addr is #0, any previous list is discarded; in this 
form, the argument link must be omitted 

link is an optional argument that, if present, specifies linking of 
tables on successive calls to .DEVICE. If the argument is 
omitted, the list referenced in the previous .DEVICE request 
is replaced by the new list. The argument must be supplied to 
cause linking of lists; however, linked and unlinked list types 
cannot be mixed 



Request Format: 

Nonlinking 


Linking 


RO -» area: 


14 


RO — > area: 


14 1 




addr 


addr 



NOTE 

The list referenced by addr must be in either linking or non- 
linking format. The different formats are shown below. Both 
formats must be terminated with a separate, zero-value 
word. Linking format must also have a zero-value word as its 
first word. 



Nonlinking 


Linking 


addr: 


address 


addr: 







value 


address 




address 


value 




value 


address 




' 


value 




' 




address 




value 




address 







value 
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Errors: 

None. 
Example: 



.TITLE DEVICE. MfiC 



.DEVICE - This is an example in the use of the .DEVICE request. 
The example shows hou .DEVICE is used to disable interrupts from 
a device upon termination of the pro9ram. In this case the deuioe 
is a DLll Serial Line Interface. 



START: 



FINIi 
BUSY: 



AREA: 
LIST: 



BUFFR: 



NOVEC: 



.MCALL 
.GLOBL 
.DEVICE 

.PROTECT 
BCS 



JSR 

.MORD 

.MORD 



. DEVICE . . EX IT . . PROTECT . . UNPROTECT .. PRINT 
DLll 



»AREft.»LIST 



»AREA.»300 
BUSY 



R5iDLll 

128. 

BUFFR 



.UNPROTECT »AREA.»300 
.EXIT 



.PRINT 

.EXIT 

.BLKM 

.MORD 

.MORD 

.MORD 

.REPT 
.A5CIZ 
.ENDR 
.ASCIZ 

.END 



ONOVEC 

3 

17B500 







iSetup to disable DLll interrupts on 

i.EXIT or "C-C 

iProtect the DLll uectors 

iBranch if already protected 

!Set UP data to transmit over DLll 

iUse DLll xfer routine (see .INTEN example) 
iAr juments . . .Mo rd count 
iOata buffer addr 
iContinue processing... 

{...eventually to exit program 

iPrint error messaSe... 

; then exit 

iEMT ArSument block 

iCSR of DLll 

iFi 11 it uith '0' 

SLi St te rminato r 

SData to send over DLll 

;S lines of 32 characters... 



8. 

/Hello DLll... Are You There ??/ 

/?Vector already protected?/ iError messaSe text 

START 



2.20 .DRAST (Device Handler Only) 

The .DRAST macro sets up the interrupt and abort entry points, lowers the 
processor priority, and references a global symbol $INPTR, which contains 
a pointer to the $INTEN routine in the resident monitor. This pointer is 
filled in by the bootstrap (for a system device) or at .FETCH time (for a data 
device). 

Macro Call: .DRAST name,pri[,abo] 

where: 

name is the two-character device name 

pri is the priority of the device, and also the priority at which 

the interrupt service code is to execute 

abo is an optional argument that represents the label of an abort 

entry point. If you omit this argument, the macro generates 
an RTS PC instruction at the abort entry point, which is the 
word immediately preceding the interrupt entry point 
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Example: 



.TITLE 



SP.MflC 



i SP.MAC - This is an eKample of a simplei RT-11 device driuer to illustrate 

! the use of the .DRBEG, .DRAST, .DRFIN, . DREND , .FORK 8. .QELDF requests, 

i This driuer could be used to output to a serial ASCII p rinte r- te rminal 

i over a DLU Serial Line Interface. To use this driver as an RT-11 deuice 

i handler) simply install it uia the INSTALL command (ea, 'INSTALL SP'). 



.MCALL 

, IIF NDF MMG$T. 
.IIF NDF ERL*G. 
, IIF NDF TIM»ITi 



.DRBEG ,. DRAST .. DRFIN .. DREND .. OELDF ,. FORK 



MMG*T=0 
ERL*G=0 
TIM»IT=0 



JDefine these in case not 
iassembled with SYSCND.MAC 



.IIF NDF SP$yEC. 
.IIF NDF SP$CSR. 
. IIF NDF SP$PRI , 



SP»VEC=30a 
SP$CSR=17E50a 

sp«PRi=a 



IDERR = 1 

SPSTS = 20000 

iDeuice Status = Write only 

SPSIZ = 



iDefine default uector 
iDefine default CSR addr 
iDefine default deuice priority 

iHard I/O error bit definition 



.OELDF 



iO.BLKN = a 
iOSCSW = -2 
iO$BUFF = a 
iO$WCNT = B 



SPSTRT: 



SPCOE: 
SPLOE: 



SPRET: 



.DRBEG 

.WORD 
.WORD 
.WORD 
.WORD 

.WORD 

.WORD 

.WORD 

.WORD 

MOV 

ASL 

BCC 

BEO 

BIS 

RETURN 



iDeuice Sije = (Char deuice) 

iUse .C3ELDF to define Q-Elew offsets 
iAmonj others i of interest to us are: 
iOffset to BlocK a (SPCOE => O.BLKN) 
iOffset from O.BLKN to CSW pointer 
' " " " " Userbufferptr 
' " " " " W r d c u n t 

SP .SP$i.iEC, SPSIZ .SPSTS iBeain driver code with .DRBEG 
iMACRO expansion is... 

<SPEND-SPSTRT> iSise of driver (handler) 

^ iSizeofdeuioe 

20000 iDeuice status (Write only) 

ERL$G+<MMG$T»2>+<TIM«IT»a>iDefault options 
iBeSinnina of driver 
i In te r rupt vector 

iOffset to Int SVC rtne & Priority 
iOueue element pointers 
>(Point to 3rd uord in element!) 
iR4 => Current 0-Element 
iMaKe word count byte count 
iA read from a write/only deuice? 
iZero word count. ..Just exit 
iEnable DL-11 interrupt 
iReturn to monitor 



*03ao 



SPVEC+a 

SPINT-. 





SPCOE ,R4 

0»WCNT(Ra) 

SPERR 

SPDUN 

«100 ,e»SP$CSR 



i INTERRUPT SERVICE ROUTINE 





.DRAST 


SP,SP$PRI 


» 


RTS 


PC 


iSPINT: 


:, JSR 


R5.@»INPTR 


i 


.WORD 


•~c<sp$PRi»-oao>a,"03ao 




MOV 


SPCOE, R4 




TST 


@»SP*CSR 




BMI 


SPRET 




BIG 


«100,@»SP«CSR 




.FORK 


SPFORK 


SPNXT: 


TSTB 


@»SP»CSR 




BPL 


SPRET 




MOVB 


eO$BUFF(R4) .e»SP$CSR + 




INC 


0»BUFF(Ra) 




INC 


0*WCNT(Ra) 




BEO 


SPDUN 




BR 


SPNXT 


SPERR: 


BIS 


»IOERR.@0$CSW(Ra) 


SPDUN: 


.DRFIN 


SP 



iUse .DRAST to define Int Sue Sect. 

iMACRO expansion... 

lAbort Entry Point 

iDo a .INTEN to alert monitor 

iand drop processor priority 

iRa => 0-Element 

iYes . . . 'hans ' until read> 
iDisable inter rupts 
iContinue at FORK level 
ils device ready? 
iNo...ao wait 'till it is 
liXfer byte from buffer to 
iBump the buffer pointer 
iand the word count (it's 
iBranch if done 
iTry to output another character 



DL-11 
nesat i ve ! ) 



iSet error bit in CSW 

iUse .DRFIN to return to Monitor 

iMACRO expansion... 
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Moy 


PCiR4 




ADD 


SSPCOE-, .R4 




Moy 


easa.RS 




JMP 


@-0270(R5) 


SPFDRK: 


.UDRD 


>0 lO lO 




.DREND 


SP 


i*INPTR! 


:.WORD 





i»FKPTR: 


: .UORD 





iSPEND = 


= , 





iCaloulate PIC addr of current 

iiueue element pointer 

iPut addr of base of RMON in R5 

iJump to handler completion in monitor 

!ForK Queue Element 

iUse .DREND to end code 

iMACRO expansion . . . 

iAddr of .INTEN code in RMON 

iAddr of .FORK processor in RMON 

iEnd of driuer 



.END 



2.21 .DRBEG (Device Handler Only) 

The .DRBEG macro sets up the information in block and the first five 
words of the handler. This macro also generates the appropriate global 
symbols for your handler. Before you use .DRBEG, invoke .DRDEF to de- 
fine xx$CSR, xx$VEC, xxDSIZ, and xxSTS (see Section 2.23). 

Macro Call: .DRBEG name 

where: 

name is a two-character device name 
Example: 

Refer to the example for .DRAST. 



2.22 .DRBOT (Devioe Handler Only) 

The .DRBOT macro sets up the primary driver. A primary driver must be 
added to a standard handler for a data device to create a system device 
handler. The .DRBOT macro invokes the .DREND macro (see Section 2.24) 
to mark the end of the handler so that the primary driver is not loaded into 
memory during normal operations. 

Macro Call: .DRBOT name,entry,read[,CONTROL = arg...,arg][,SIDES = n] 
where: 



name 
entry 
read 
CONTROL 



SIDES 



is the two-character device name 

is the entry point of the software bootstrap routine 

is the entry point of the bootstrap read routine 

defines the types of controllers supported by this han- 
dler. The values for arg can be UBUS or QBUS. If 
CONTROL is omitted, both Unibus and Q-bus are as- 
sumed. This is correct for all supported handlers 

specifies single- or double-sided diskettes. If omitted, 
single-sided diskettes are assumed. This is correct for 
all supported handlers 
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The .DRBOT macro puts a pointer to the start of the primary driver into 
location 62 of the handler file. It puts the length (in bytes) of the primary 
driver into location 64. Location 66 of the handler file contains the offset 
from the start of the primary driver to the start of the bootstrap read rou- 
tine. The .DRBOT macro is called before the .DREND macro that you issue. 
The code for the primary driver is placed between the .DRBOT and 
.DREND calls. 

Example: 

Refer to the RT—11 Software Support Manual for an example showing 
the use of .DRBOT. 

2,23 .DRDEF (Device Handler Only) 

The .DRDEF macro sets up handler parameters, calls the driver macros 
from the library, and defines useful symbols. 

Macro Call: .DRDEF name,code,stat,size,csr,vec 

where: 

name is the two-character device name 

code is the numeric code that is the device identifier value for the 
device 

stat is the device status bit pattern. The value for stat may use 
the following symbols: 

FILST* = 100000 SPECL$ = 10000 ABTIO$ = 1000 
RONLY$ = ^0000 HNDLR$ = 4000 UARSZ$ = 400 
WONLY$ = 20000 SPFUN* = ZOOO 

size is the size of the device in 256-word blocks 

csr is the default value for the device's control and status regis- 

ter 

vec is the default value for the device's vector 

The .DRDEF macro performs the following operations: 

1. A .MCALL is done for the following macros: .DRAST; .DRBEG; 
.DRBOT; .DREND; .DRFIN; .DRINS; .DRSET; .DRVTB; .FORK; 
.QELDF. 



2. If the system generation conditionals TIM$IT, MMG$T, or ERL$G are 
undefined in your program, they are defined as zero. If time-out support 
is selected, the .DRDEF macro does a .MCALL for the .TIMIO and 
.CTIMIO macros. 

3. The .QELDF macro is invoked to define symbolic offsets within a queue 
element. 

4. The symbols listed above are defined for the device status bits. 
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5. The following symbols are defined: 

HDERR$=1 !HARD ERROR BIT IN THE CSW 

EOF$ = 2oooo ;end of file bit in the CBW 

6. The symbol xxDSIZ is set to the value specified in size. 

7. The symbol xx$COD is set to the specified device identifier code. 

8. The symbol xxSTS is set to the value of the device identifier code plus 
the status bits. 

9. If the symbol xx$CSR is not defined, it is set to the default csr value. 

10. If the symbol xx$VEC is not defined, it is set to the default vector value. 

11. The symbols xx$CSR and xx$VEC are made global. 

You should invoke the .DRDEF macro near the beginning of your handler, 
after all handler specific conditionals are defined. 

Example: 

Refer to the RT-11 Software Support Manual for an example showing 
the use of .DRDEF. 



2.24 .DREND (Device Handler Only) 



The .DREND macro generates the termination table for the termination 
section of the device handler. 

Macro Call: .DREND name 

where: 

name is the two-character device name 

The generation of the termination table, dependent upon certain condi- 
tions, is as follows: 

Label Addresses 

$RLPTR: .WORD ($RELOC) 

$MPPTR: .WORD ($MPPHY) 

$GTBYT: .WORD ($GETBYT) 

$PTBYT: .WORDO ($PUTBYT) 

$PTWRD: .WORD ($PUTWRD) 

$ELPTR: .WORD ($ERLOG) 

$TIMIT: .WORD ($TIMIO) 

$INPTR: .WORD ($INTEN) 

$FKPTR: .WORDO ($FORK) 

The generation of the labels depends upon the special features chosen dur- 
ing the system generation process. All the pointers in the termination sec- 
tion are initialized when the handler is loaded into memory with the 
.FETCH request. If the device handler is a system device, the pointers are 
initialized at boot time with the addresses shown in the address column. 
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The addresses are located within the monitor. The first five addresses are 
the locations of subroutines in the resident monitor that are available to 
device handlers in an extended memory environment. Device I/O time-out 
service is provided by $TIMIO and error logging is provided by $ERLOG. 
The $INPTR and $FKPTR labels are always filled in by a .FETCH or 
LOAD command. 

Example: 

Refer to the example for .DRAST. 

2.25 .DRFIN (Device Handler Only) 

The .DRFIN macro generates the instructions for the jump back to the 
monitor at the end of the handler I/O completion section. The macro makes 
the pointer to the current queue element a global symbol, and it generates 
position-independent code for the jump to the monitor. When control passes 
to the monitor after the jump, the monitor releases the current queue ele- 
ment. 

Macro Call: .DRFIN name 

where: 

name is the two-character device name 
Example: 

Refer to the example for .DRAST. 

2.26 .DRINS 

The .DRINS macro sets up the installation code area in block of a device 
handler. The .DRINS macro defines addresses that contain the CSR ad- 
dresses listed by RESORC (display CSRs) and the CSR checked by the 
INSTALL keyboard command. The .DRINS macro also defines the system 
and data device installation entry points. 

The .DRINS macro has the following syntax: 

.DRINS name,<csr,csr,...> 

where: 

name represents the two-letter device mnemonic for the device 
whose handler installation code you are setting up. 

csr represents a symbolic CSR address for that device. If more 

than one display CSR exists, separate them with commas 
and enclose the list in angle brackets (<>). With multiple 
display CSRs, you do not have to list the first CSR. 

When the .DRINS macro is processed, the following addresses are defined 
based on the CSR addresses you supply. 
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INSCSR Installation check CSR 

DISCSR First display CSR 

DISCSn Subsequent display CSRs if any exist (n begins at 2 and is 
incremented by 1 for each subsequent display CSR) 

In addition, the .DRINS macro sets the location counter to 200 (INSDAT 
= : 200) for the data device installation entry point, and defines the label 
INSSYS as 202 (INSSYS = : 202), the system device installation entry 
point. 

The following example shows the installation code generated by a .DRINS 
macro used for a DX handler with two controllers. 





.DRINS 


DX.<DX*CS2> 


iGENERflTE INSTflLLflTION CODE 
iFOR TWO-CONTROLLER RXOl 


. = 172 










.WORD 





!END OF LIST 


DISCSZ 


.WORD 


DX$CS2 


iSECONDflRY DISPLAY CSR 


DISCSR 


.WORD 


DX*CSR 


iPRIMflRY DISPLAY CSR 


INSCSR 


.NORD 


DX$CSR 


ilNSTALL CSR 


INSDflT 








.=202 








INSSYS 








.=200 









The next example shows the installation code generated by a 
macro used for a DU handler with three controllers. 



.DRINS 



.DRINS 



DU,<DUtCSZ,DU«CS3> 



■GENERATE INSTALLATION CODE 
iFOR THREE-CONTROLLER 
iMSCP DEVICE 



= 170 





.WORD 





!END OF LIST 


DISCS3 


.WORD 


DUtCSS 


iTHIRD DISPLAY CSR 


DISCS2 


.WORD 


DU*CS2 


;SECONDARY DISPLAY CSR 


DISCSR 


.WORD 


DU$CSR 


iFIRST DISPLAY CSR 


INSCSR 


.WORD 


DU$CSR 


; INSTALL CSR 


INSDAT 








.=202 








INSSYS 








.=200 









2.27 .DRSET (Device Handler Only) 

The .DRSET macro sets up the option table for the SET command in block 
of the device handler file. The option table consists of a series of four- word 
entries, one entry per option. Use this macro once for each SET option that 
is used. When used a number of times, the macro calls must appear one 
after another. 



Macro Call: 
where: 

option 



val 



DR.SRT nnt.inn vnl rfriF mnHal 



is the name of the SET option, such as WIDTH or CR. The 
name can be up to six alphanumeric characters long and 
should not contain any embedded spaces or tabs 

is a parameter that is passed to the routine in Register R3. 
It can be a numeric constant, such as minimum column 
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width, or any one-word instruction that is substituted for an 
existing one in block 1 of the handler. It must not be a zero 

rtn is the name of the routine that modifies the code in block 1 

of the handler. The routine must follow the option table in 
block and must not go above address 776 

mode is an optional argument to indicate the type of SET parame- 
ter. A NO indicates that a NO prefix is valid for the option. 
NUM indicates that a decimal numeric value is required. 
OCT indicates that an octal numeric value is required. 
Omitting this argument indicates that the option takes nei- 
ther a NO prefix nor a numeric argument 

The .DRSET macro does an .ASECT and sets the location counter to 400 for 
the start of the table. The macro also generates a zero word for the end of 
the table and leaves the location counter there. Thus routines to modify 
codes are placed immediately after the .DRSET calls in the handler, and 
their location in block of the handler file is made certain. 

Example: 

Refer to the RT-11 Software Support Manual for an example of 
.DRSET. 

2.28 .DRVTB (Device Handler Only) 

The .DRVTB macro sets up a table of three- word entries for each vector of a 
multivector device. The table entries contain the vector location, interrupt 
entry point, and processor status word. You must use this macro once for 
each device vector. The .DRVTB macros must be placed consecutively in 
the device handler between the .DRBEG macro and the .DREND macro. 
They must not interfere with the flow of control within the handler. 

Macro Call: .DRVTB name,vec,int[,ps] 



where: 



name is the two-character device name. This argument must be 
blank except for the first-time use of .DRVTB 

vec is the location of the vector, and must be between and 474 

int is the symbolic name of the interrupt handling routine. It 

must appear elsewhere in the handler code. It generally 
takes the form ddlNT, where dd represents the two-charac- 
ter device name 

ps is an optional value that specifies the low-order four bits of 

the new Processor Status Word in the interrupt vector. This 
argument defaults to zero if omitted. The priority bits of the 
PSW are set to 7 even if you omit this argument 



Example: 



Refer to the RT-11 Software Support Manual for an example of 
.DRVTB. 
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2.29 .DSTATUS 

This .DSTATUS request obtains information about a particular device. 

Macro Call: .DSTATUS retspc,dnam 

where: 

retspc is the address of a four-word block that stores the status 
information 

dnam is the address of a word containing the Radix-50 device 
name 

.DSTATUS looks for the device specified by dnam and, if successful, returns 
four words of status starting at the address specified by retspc. The four 
words returned are as follows: 

Word 1 Status Word 

Bits 0-7: The low-order byte contains a number that identifies the 
device in the system. The values are currently defined in 
octal as follows: 

= RKOSDisk 

1 = TCll DECtape 

2 = Error Logger 

3 = Line Printer 

4 = Console Terminal or Batch Handler 

5 = RL01/RL02 Disk 

6 = RX02 Diskette 

7 = PC 11 High-speed Paper Tape Reader and 

Punch 

10 = Reserved (V2 PP handler) 

11 = TUlO Magtape 

12 - RFll Disk 

13 = TAll Cassette 

14 = Card Reader (CR11,CM11) 

15 = Reserved 

16 = RJS03/RJS04 Fixed-head Disk 

17 = Reserved 

20 = TJU16 Magtape 

21 = RP02/RP03 Disk 

22 = RXOl Diskette 

23 = RK06/RK07 Disk 

24 = Reserved 

25 = Null Handler 
26-30 = Reserved (DECnet) 

31-33 = Reserved (CTS-300,LQ,LR,LS) 

34 = TU58 DECtape II 

35 = TSll Magtape 

36 = PDT-1 1/130 

37 = PDT-11/150 
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40 = Reserved 

41 = Serial Line Printer Handler (LS) 

42 = Message Queue Handler (MQ) 

43 = DRVll-J Interface (MRRT) 

44 = Down-line Load Handler (XT) (MRRT-11 

only) 

45 = Reserved 

46 = Logical Disk Handler 

47 = KT-11 VM Handler 

50 = MSCP Class Disk Handler 

51 = Single-line Editor 

52 = RX50 Diskette (Professional 325/350) 

53 = RD5G/RD51 Disk (Professional 350) 

54 = Professional Interface (PI) 

55 = Transparent Spooler (SP) 

57 = Communication Port (Professional 325/350 or 
DL(V)-ll) 

Bit 8: 1 = Handler can access variable-sized volumes and sup- 

ports .SPFUN 373 
= All volumes used by this device are the same size 

Bit 9: 1 = Enter handler at abort entry whenever program ter- 

minates for any reason 
0= Do not enter at abort entry point unless conditions 
for bit 11 are satisfied 

Bit 10: 1 = Handler accepts .SPFUN requests (for example, MT, 

CT, DX) 
= No .SPFUN requests accepted 

Bit 11: 1= Enter handler abort entry every time a job is 

aborted 
= Handler abort entry taken only if there is an active 
queue element belonging to aborted job 



Bit 12: 

Bit 13 
Bit 14 
Bit 15 



1= Non RT-11 directory-structured device (magtape, 
cassette) 

1 = Write-only device (line printer, serial line printer) 

1 = Read-only device (card reader, paper tape reader) 



1 = Random-access device (disk, DECtape) 
0= Sequential-access device (line printer, paper tape, 
card reader, magtape, cassette, terminal) 

Word 2 Handler Size 

The size of the device handler in bytes. 

Word 3 Load Address + 6 

Non-zero implies the handler is now in memory: zero implies that it 
must be fetched before it can be used. The address returned is the 
load address of the handler -1-6. 
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Word 4 Device Size 

The size of the device (in 256-word blocks) for block-replaceable de- 
vices; for sequential-access devices, the smallest-sized volume for 
variable-sized devices. The last block on the device is the device size 
-1. 

The device name can be a user-assigned name. .DSTATUS information is 
extracted from the device handler. Therefore, this request requires the han- 
dler for the device to be present on the system device and installed on the 
system. 



Errors: 

Code 


Example: 



Explanation 

Device not found in tables. 



.TITLE DSTftT.MAC 

;+ ■ 

i , DSTATUS - This is an example in the use of the .DSTATUS request. 

i The example uses the "special" mode of CSl to Set an input 

i specification from the console terminal) then uses the .DSTATUS 

i request to determine if the output deuice's handler is loaded! 

i if not I a .FETCH request is issued to load the handler into 

i memory. Finally a .DELETE request is issued to delete the specifiet 

! file. 



.MCALL 



. DSTATUS.. PR I NT.. EXIT.. FETCH.. CS I SPC. DELETE 



START! 


.CSISPC 


«DUTSP.«DEFEXT 




.DSTAT 


»STAT.»QUTSP 




TST 


STAT+a 




BNE 


2$ 




.FETCH 


«HANLOD.«INSPEC 




BCC 


Z* 




.PRINT 


WFEFAIL 




.EXIT 




Zi: 


.DELETE 


»AREA.«0.«INSPEC 




BCC 


3$ 




.PRINT 


«NOFIL 




BR 


START 


3$: 


.PRINT 


BFILDEL 




.EXIT 




AREA: 


.BLKW 


2 


STAT: 


.BLKW 


d 


DEFEXT: 


.NORD 


.0 .0 .0 


FEFAIL: 


.ASCIZ 


/?. FETCH Failed?/ 


NOFILs 


.ASCIZ 


/?File Not Found?/ 


FILDEL! 


.ASCIZ 
.EVEN 


/!File Deletedl/ 


OUTSP! 


.BLKW 


5»3 


INSPEC: 


.BLKW 


a*6 


HANLOD: 


.BLKW 


1 




.END 


START 



iUse .CSISPC to Set output spec 

iCheok on the output device 

.(CSISPC catches illesal deuices!) 

iSee if the deuice is resident 

.Branch if already loaded 

ilt's not loaded ... b rins it into memory 

iBranoh if successful 

.Fetch f ai 1 ed . . . p rint error messaSe 

ithen exit p rosram 

iNow delete the file 

.Branch if successful 

.Print error messaSe 

iThen t ry aSain 

.AoKnowledSe successful deletion 

ithen exit pros ram 

iEMT Arsument blocK 

iBlocK for status 

.No default extensions 

.Fetch failed messaSe 
.File not found 
iDelete acKncu/led Sment 
.Fix bounda ry 

iOutPUt specs So here 

i Input specs So he re 

iHandlers besin loadins here (if necessary) 



2.30 .ELAW (XM Only) 



The .ELAW request eliminates a virtual address window. An implied un- 
mapping of the window occurs when its definition block is eliminated. 
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Macro Call: .ELAW area[,addr] 

where: 

area is the address of a two-word EMT argument block 

addr is the address of the window definition block for the window 
to be eliminated 

Request Format: 

RO — > area: 



36 



addr 



Errors: 

Code 
3 

Example: 

Refer to the example for the .CRAW request 



Explanation 

An invalid window identifier was specified. 



2.31 .ELRG (XM Only) 



The .ELRG request directs the monitor to eliminate a dynamic region in 
physical memory and return it to the free list where it can be used by other 
jobs. 

Macro Call: .ELRG area [,addr] 

where: 

area is the address of a two- word EMT argument block 

addr is the address of the region definition block for the region to 
be eliminated. Windows mapped to this region are unmapped. 
The static region cannot be eliminated 

Request Format: 

RO -» area: 



36 



addr 



Errors: 

Code Explanation 

2 An invalid region identifier was specified. 

Example: 

Refer to the example for the .CRAW request. 



2.32 .ENTER 



The .ENTER request allocates space on the specified device and creates a 
tentative entry in the directory for the named file. The channel number 
specified is associated with the file. 
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Macro Call: .ENTER area,chan,dblk,len[,seqnum] 
where: 

area is the address of a four-word EMT argument block 

chan is a channel number in the range 0-376(octal) 

dblk is the address of a four-word Radix-50 descriptor of the 

file to be operated upon 

len is the file size specification. If the argument is omitted, it 

is not set to in area. An argument of #0 must be speci- 
fied to accomplish this. If an argument is left blank, the 
corresponding location in area is assumed to be set 

The value of this argument determines the file length allo- 
cation as follows: 

either half the largest empty entry or the entire sec- 
ond-largest empty entry, whichever is larger. (A max- 
imum size for nonspecific .ENTER requests can be 
patched in the monitor by changing resident monitor 
offset 314; refer to the example for .PVAL) 

m a file of m blocks. The size, m, can exceed the maxi- 
mum mentioned above 

-1 the largest empty entry on the device 

seqnum is a file number for magtape or cassette. Programming for 
specific devices such as magtape or cassettes is discussed 
in detail in Chapter 10 of the RT-11 Software Support 
Manual. For cassette operation, if this argument is blank, 
a value of is assumed 

For magtape, seqnum describes a file sequence number. 
The action taken depends on whether the file name is 
given or is null. The sequence number can have the follow- 
ing values: 

rewind the magtape and space forward until the file 
name is found or until logical end-of-tape is detected. 
If the file name is found, an error is generated. If the 
file name is not found, then enter file. If the file name 
is a null, a non-file-structured lookup is done (tape is 
rewound) 

n position magtape at file sequence number n if n is 
greater than zero and the file name is not null 

-1 space to the logical end-of-tape and enter file 

-2 rewind the magtape and space forward until the file 
name is found, or until logical end-of-tape is detected. 
The magtape is now positioned correctly. A new logi- 
cal end-of-tape is implied 
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Request Format: 
RO — > area: 



2 chan 



dblk 



len 



seqnum 



On return from this call, RO contains the size of the area actually allocated 
for use. 

The file created with an .ENTER request is not a permanent file until a 
.CLOSE request is given on that channel. Thus, the newly created file is 
not available to .LOOKUP, and the channel cannot be used by .SAVE- 
STATUS requests. However, it is possible to read data that has just been 
written into the file by referencing the appropriate block number. When 
the .CLOSE to the channel is given, any existing permanent unprotected 
file of the same name on the same device is deleted and the new file be- 
comes permanent. Although space is allocated to a file during the .ENTER 
operation, the actual length of the file is determined when .CLOSE is re- 
quested. 

Each job can have up to 255 files open on the system at any time. If re- 
quired, all 255 can be opened for output with the .ENTER function. 

When an .ENTER request is made, the device handler must be in memory. 
Thus, a .FETCH should normally be executed before an .ENTER can be 
done. 

Notes: 

When using the zero-length feature of .ENTER, keep in mind that the 
space allocated is less than the largest empty space. This can have an 
important effect in transferring files between devices (particularly DEC- 
tape and diskette) that have a relatively small capacity. For example, 
transferring a 200-block file to a diskette, on which the largest available 
empty space is 300 blocks, does not work with a zero-length .ENTER. Since 
the .ENTER allocates half the largest space, only 150 blocks are really 
allocated and an output error occurs during the transfer. When transfer- 
ring from A to B, with the length of A unknown, do a .LOOKUP first. This 
request returns the length so that value can be used to do a fixed-length 
.ENTER. The .ENTER request generates hard errors when problems are 
encountered during directory operations. These errors can be detected after 
the operation with the .SERR request. 

Errors: 

Code Explanation 

Channel is in use. 

1 In a fixed-length request, no space greater than or equal to 
m was found; or the device or the directory was found to be 
full. 

3 A file by that name already exists and is protected. A new 

file was not opened. 
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Example: 



.TITLE ENTER. MAC 



.ENTER - This is an eKample in the use of the .ENTER request. 
The exaiTiple makes a copy of the file 'TECO.SAV on device DK: 





.MCALL 


.LOOKUP. 


ENTER. 


WRITW 


..READW, .CLOSE 






.MCALL . 


.PRINT. .EXIT 










ERRBYT=52 












START: 


.LOOKUP 
BCB 


«AREAi«0 
5t 


OTECO 




iLooKup file TECO.SAV 
iB ranch if not there! 






MOV 


R0.R3 




X 


iCopy size of file to R3 






.ENTER 


t>AREA.»l 


WTFILE 


.R3 


iEnter a neu file of same size 






BCS 


Bt 






.Branch if failed 






CLR 


BLK 






.Initialise blocK « to zero 




1$: 


.READW 

BCC 

TSTB 

BEO 

MOV 

BR 


»AREA .aO 

2* 

e»ERRBYT 

3t 

SRERR.RO 

7* 


SBUFFR 


.»25S. 


.BLK iRead a block 
.Branch if successful 
!Was error EOF? 
.Branch if yes 

.Hard read error messase to RO 
.Branch to print messaSe 




2$: 


.WRITW 


•AREA.ttl 


SBUFFR 


.tt25B. 


.BLK iWrite a block 






INC 


BLK 






iBump block » (doesn't affect C bi 


t) 




BCC 


1$ 






.Branch if write uas ok 






MOV 


SWERR.RO 






iRO => Write error messaSe 






BR 


7* 






.Branch to print messaSe 




3$: 


.CLOSE 

MOV 

BR 


«1 

• DONE.RO 

7$ 






.Make neu file permanent 
iRO => Done messaSe 
.Branch to print messaJe 




5*: 


MOV 


«NOFIL ,R0 




>R0 => File not found messaSe 






BR 


7$ 






iB ranch to print it 




B$: 


MOV 


SNOENT.RO 




iRO => Enter Failed messaSe 




7*: 


.PRINT 
.EXIT 








iPrint messaSe on console termina 
i the SKi t prosram 


1 


AREA: 


.WORD 









.EMT ArSument block 




BLK: 


.WORD 


.0 .0 .0 






» 




BUFFR: 


.BLKW 


25B. 






iI/0 Buffer 




TECO: 


.RAD50 
.RAD50 
.RAD50 


/DK/ 

/TECO/ 

/SAV/ 






iFi le descriptors... 




TFILE: 


.RAD50 
.RAD50 
.RAD50 


/DK/ 

/OLDTEC/ 

/SAV/ 










NOFIL: 


.ASCIZ 


/?Fi le not found 


?/ 


iMessaSe text . . . 




NOENT: 


.ASCI2 


/?. ENTER 


Failed? 


/ 






NERR: 


.ASCIZ 


/?Write E 


r ro r?/ 








RERR: 


.ASCIZ 


/?Read Error?/ 








DONE: 


.ASCIZ 


/TECO Copy Complete/ 








.END 


START 














The .EXIT request causes the user program to terminate. When used from 
a background job under the FB monitor or XM monitor, or in SJ, .EXIT 
causes KMON to run in the background area. All outstanding mark time 

T'OiTinoo'^o ov»o r**^irtrta.la,ri A ■Kitr Tilt ■►•Qz-nnoo-i-a o -r* i^ /i-v** /^rvw^-r*l-^4--i ^-vi-^ vtj-fcii4"« w* j-».(-< vxr^v% J-i-v^ <-*• 
xv^v^i^^k^uo C4.xv^ ^cAx±v/V^J.^vi.* xa.xj.jr x/ v-r X v./vj^u.t:^oL>i:3 c:xxx\A/ \JX w/xxlUxc;bJ.VXJL XV/U.U111C;0 L/<c;ii.U.Xi.lg 

for that job are allowed to complete. If part of the background job resides 
where KMON and USR are to be read and SET EXIT SWAP is in effect, the 
user job is written onto the system swap blocks (the file SWAP.SYS). 
KMON and USR are then loaded and control goes to KMON in the back- 
ground area. If SET EXIT NOSWAP is in effect, the user program is simply 
overwritten when a .EXIT is done. If RO = when the .EXIT is done, an 
implicit .HRESET is executed when KMON is entered, disabling the subse- 
quent use of REENTER, START, or CLOSE. 
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The .EXIT request allows a user program to pass command lines to KMON 
in the chain information area (locations 500-777octal) for execution after 
the job exits. This is performed under the following conditions: 

1. The word (not byte) location 510 must contain the total number of bytes 
of command lines to be passed to KMON. 

2. The command lines are stored beginning at location 512. The lines 
must be .ASCIZ strings with no embedded carriage return or line feed. 
For example: 

.=510 
.WORD B-A 
A: .ASCIZ /COPY A.MAC B.MAC/ 
.ASCIZ /DELETE A.MAC/ 



3. The user program must set bit 5 or bit 11 in the Job Status Word 
immediately before doing an .EXIT, which must be issued with 
RO = 0. 

When the .EXIT request is used to pass command lines to KMON, the 
following restrictions are in effect: 

1. If bit 11 of the JSW is set and if the feature is used by a program that is 
invoked through an indirect file, the indirect file context is aborted 
before executing the supplied command lines. Any unexecuted lines in 
the indirect file are never executed. 

2. If bit 5 of the JSW is set and the feature is used by a program invoked 
through an indirect file, the indirect file context is preserved across the 
.EXIT request. 

3. An indirect file can be invoked, using the steps described above, only 
if a single line containing the indirect file specification is passed to 
KMON. Attempts to pass multiple indirect files or combinations of indi- 
rect command files and other KMON commands yield incorrect results. 
An indirect file must be the last item on a KMON command line. 

The .EXIT request also resets any .CDFN and .QSET calls that were done 
and executes an .UNLOCK if a .LOCK has been done. Thus, the CLOSE 
command from the keyboard monitor does not operate for programs that 
perform .CDFN requests. 

An attempt to use a .EXIT from a completion routine aborts the running 
job. 

NOTE 

You must make sure that the data being passed to KMON is 
not destroyed during the .EXIT request. Extreme care should 
be exercised so that the user stack does not overwrite this 
data area. If the user passes command lines to KMON, the 
stack pointer should be reset to lOOO(octal) or above before 
an exit is made. 
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Macro Call: .EXIT 
Errors: 

None. 
Example: 

.TITLE EXIT. MAC 
i + 

i .EXIT - This is an example in the use of the .EXIT request. 
i The example demonstrates how a oommand line may be passed to 
i Keyboard Monitor after Job execution is stopped. 





.MCALL 


.EXIT 


CHNIF* 


= aooo 




JEW 


= 44 




START: 


MOM 


«510,R0 




Moy 


SCMDSTR.RI 




Moy 


ttSTART.SP 


10$: 


Moye 


<R1)+.(R0)+ 




CMP 


Rl ittCMDEND 




BLO 


10* 




BIS 


ttCHNIF$i@»JSW 




CLR 


RO 




.EXIT 




CMDSTR: 


.WORD 


CMDEND-CMDSTR 




.ASCIZ 


"DIRECT/FULL * . MAC 


CMDEND: 


.EVEN 






.END 


START 



iChain bit in JSW 

i JSW location 

iRO => Communication area 

iRl => Command strins 

iMaKe sure that the staoK is 

inot in the communication area... 

iCopy command strinS 

i D n e ? 

iBranch if not 

iSet the "chain" bit to alert KMON that 

ithere's a command in the communication area 

!R0 must be zero ! 

iEx i t the pro Sram 



2.34 .FETCH/.RELEAS 



The .FETCH request loads device handlers into memory from the system 
device. 

Macro Call: .FETCH addr,dnam 

where: 

addr is the address where the device handler is to be loaded 

dnam is the pointer to the Radix-50 device name 

The storage address for the device handler is passed on the stack. When the 
.FETCH is complete, RO points to the first available location above the 
handler. If the handler is already in memory, RO contains the same value 
that was initially specified in the argument addr. If the argument on the 
stack is less than 400(octal), it is assumed that a handler .RELEAS is being 
done. (.RELEAS does not dismiss a handler that was loaded from the 
KMON; an UNLOAD must be done.) After a .RELEAS, a .FETCH must be 
issued in order to use the device again. 

Several requests require a device handler to be in memory for successful 
operation. These include: 

.CLOSE .READC .READ .SFDAT 

.LOOKUP .WRITC .WRITE .FPROT 

.ENTER .READW .SPFUN 

.RENAME .WRITW .DELETE 
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When running under the foreground/background monitor, handlers for the 
foreground program or a system job must be loaded with the LOAD com- 
mand before execution. 

NOTE 

I/O operations cannot be executed on devices unless the han- 
dler for that device is in memory. 

Errors: 



Code 


Example: 



Explanation 

The device name specified is not installed in the system, or 
there is no handler for that device in the system. 



.TITLE FETCH. MAC 

+ 

.FETCH - This is an example in the use of the .FETCH request. 

The example uses the "special" mode of CSI to Jet an input 

specification from the console terminal) then uses the .DSTATUS 

request to determine if the output device's handler is loaded! 

if not I a .FETCH request is issued to load the handler into 

memory. Finally a .DELETE request is issued to delete the specified 

file. 



.MCflLL 



.DSTATUS .. PRINT , . EXIT , .FETCH , .CBISPC . . DELETE 



START: 


.CSISPC 


8DUTSP,»DEFEXT 




.DSTAT 


«STAT.«OUTSP 




TST 


STAT+a 




BNE 


2$ 




.FETCH 


«HANLOD.»INSPEC 




BCC 


2* 




.PRINT 


OFEFAIL 




.EXIT 




2$: 


.DELETE 


«AREA,ttOi«INSPEC 




BCC 


3* 




.PRINT 


SNOFIL 




BR 


START 


3$: 


.PRINT 
.EXIT 


SFILDEL 


AREA: 


.BLKN 


2 


STAT: 


.8LKW 


l\ 


DEFEXT: 


.WORD 


lO lO lO 


FEFAIL: 


.ASCIZ 


/?. FETCH Failed?/ 


NOFIL: 


.ASCIZ 


/?File Not Found?/ 


FILDEL: 


.ASCIZ 
.EVEN 


/IFile Deleted!/ 


OUTSP: 


= .BLKW 


5*3 


INSPEC: 


= .BLKW 


4»B 


HANLDD: 


= .BLKW 


1 




.END 


START 



iUse .CSISPC to Set output spec 

iChecK on the output deuice 

!(CSI,SPC catches illesal devices!) 

iSee if the device is resident 

iBranch if already loaded 

ilt's not 1 oaded . . . b rins it into memory 

iBranch if successful 

iFetch failed. ..print error message 

ithen exit prosram 

!Now delete the file 

iBranch if successful 

iPrint error messase 

iThen try asain 

iAcKnouledSe successful deletion 

ithen exit prosram 

iEMT A rsument bl ooK 

iBlooK for status 

iNo default extensions 

iFetch failed messaSe 
iFi le not found 
iOelete acKnowl edsment 
iFix boundary 

iDutput specs 30 here 

i Input specs So here 

iHandlers besin loadins here (if necessary) 



The .RELEAS request notifies the monitor that a fetched device handler is 
no longer needed. The .RELEAS is ignored if the handler is (1) the system 
device, (2) not currently resident, (3) resident because of a LOAD command 
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to the keyboard monitor. .RELEAS from the foreground or system job under 
the FB monitor or the XM monitor is always ignored, since the foreground 
job in a FB environment or extended memory environment can only use 
handlers that have been loaded by the LOAD command. 

Macro Call: .RELEAS dnam 

where: 

dnam is the address of the Radix-50 device name 
Errors: 

Code Explanation 

Device name is invalid. 
Example: 

.TITLE RELEAS. MAC 

iln this exawplei the DECtape handler (DT) is loaded into memory) 
iusedf then released. If the system device is DECtapei the handler is 
ialways resident* and .FETCH will return HSPACE in RO. 

.MCALL .FETCH,. RELEAS.. EX IT.. PR I NT 



START: 


.FETCH 


• HSPACE .*DTNAME ,Lo ad DT hand 1 e r 




BCS 


FERR iNot auailable 


i Use h 


andl e r 






.RELEAS 


«DTNAME iMark DT no longer in 
i m e m r y 




BR 


START 


FERR: 


.PRINT 


«NQDT iDT not available 


DTNAMEi 


1 .RAD50 


/DT / .Name for DT handler 


NODT: 


.ASCIZ 
.EVEN 


/?DT HANDLER NOT AVAILABLE/ 


HSPACE; 




iBeSinninS of handler 
i a re a 



.END 



START 



2.35 .FORK (Device Handler and Interrupt Service Routine Only) 

The .FORK call is used when access to a shared resource must be serialized 
or when a lengthy but non-time-critical section of code must be executed. 
.FORK issues a subroutine call to the monitor and does not use an EMT 
instruction request. 

Macro Call: .FORK fkblk 

where: 

fkblk is a four- word block of memory allocated within the driver 
Errors: 

None. 
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SYSPTR=54 




FDRK=402 




.GlJAL 


»AREA t «FDRK 


ADD 


e»SYSPTR. RO 


MOl.'E 


RO, *FKPTR 



The .FORK macro expands as follows: 

.FORK fKblK 
JSR 15 »@$FKPTR 
•WORD fKblK-. 

The .FORK call must be preceded by an .INTEN call, and the address of a 
four-word block must be supplied with the request. Your program must not 
have left any information on the stack between the .INTEN and the .FORK 
call. The contents of registers R4 and R5 are preserved through the call, 
and on return registers RO through R3 are available for use. 

If you are using a .FORK call from a device handler, it is assumed that you 
are also using the other macros (.QELDF, .DRBEG, .DRAST, .DRFIN, and 
.DREND) provided for handlers. 

The .DREND macro allocates a word for $FKPTR. This word is filled in at 
bootstrap time for a system device or at LOAD or .FETCH time for a non- 
system device. 

If you want to use the .FORK macro in an in-line interrupt service routine 
rather than in a device handler, you must set up $FKPTR. The recom- 
mended way to do this is as follows: 

iAddress oontainins base 
iaddress of RMON 
iMonitor offset containins 
ioffset to fork processor 
iReturn offset in RO 
iAdd RMON base address 
iSaue as address of the 
ifork processor 



AREA: .BLKW 2 
$FKPTR: .WORD 

Once the pointer is set up, use the macro in the usual way as follows: 

.FORK fkblk 

This method permits you to preserve both R4 and R5 across the fork. 

The .FORK request is linked into a queue and serviced on a first-in first- 
out basis. On return to the driver or interrupt service routine following the 
call, the interrupt has been dismissed and the processor is executing at 
priority 0. Therefore, the .FORK request must not be used where it can be 
reentered using the same fork block by another interrupt. It also should not 
be used with devices that have continuous interrupts that cannot be dis- 
abled. The RT-11 Software Support Manual gives additional information 
on the .FORK request. 

Notes: 

For use within a user interrupt service routine, monitor fixed offset 402 
(FORK) contains the offset from the start of the resident monitor to the 
.FORK request processor. A .FORK can be done by computing the address 
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of the .FORK request processor and using a subroutine instruction. (Under 
the XM monitor, only privileged jobs can contain user interrupt service 
routines.) For example: 





SYSPTR=54 






F0RK=402 






.GVAL 


«AREA» «FORK 




ADD 


e»SYSPTRi RO 




MOV 


ROi R4 




JSR 


R5 » (Rfl) 




• WORD 


BLOCK-. 


AREA: 


.dLKW 2 




BLOCK: 


.BLKW a 





iAddress containing base 
iadd ress of RMON 
iMonitor offset oontaininsJ 
ioffset to forK processor 
iReturn offset in RO 
iAdd RMON base address 

iCall fork process 



This method destroys the contents of R4. 
Example: 

Refer to the example following the description of .DRAST. 



2.36 .FPROT 



The .FPROT programmed request sets or removes file protection on indi- 
vidual RT-11 files. A file marked as protected cannot be deleted by 
.CLOSE, .DELETE, .ENTER, or .RENAME requests. However, the con- 
tents of a protected file are not protected against modification. For example, 
a .LOOKUP of a protected file followed by a .WRITE to the file is per- 
mitted. 

Protection is enabled by setting bit 15 of a file's directory entry status word. 

Macro Call: .FPROT area, chan, dblk, prot 

where: 

is the address of a four-word EMT argument block 
is a channel number in the range 0-376(octal) 



area 
chan 
dblk 



is the address of a four-word block containing the filespec in 
Radix-50 of the file 



prot 



= #1 — to protect the file from deletion 

= #0 — to remove protection so that the file can be deleted 

Request Format: 
RO area 



43 



chan 



dblk 



prot 
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Errors: 

Code 



1 

2 

3 
Example: 



Explanation 
Channel in use 
File not found 
Invalid operation 
Invalid value for PROT 



i.FPRDTi .SFDAT example. 

iThis is an example of the use of the .FPRDT and .SFDAT 

ip ro^rammed re^iuests. It uses the "special" mode of the CSI to 

iset an input filespeo from the console terminal. .DSTATUS is 

iused to determine if the device handler is loaded. If noti a 

I. FETCH request is used to load the handler into memcry. Finally) 

ithe file is marked as protected usini the .FPRDT re=iuest and 

ithe file date is chanaed to the current system date usin9 the 

i .SFDAT request . 



.MCALL .FPRDT. .FETCH. .CSISPC, .DSTATUS. .SFDAT. .PRINT, .EXIT 



START: 



1$: 



2%: 



lot: 

EMTBLK: 

DEFEXT: 

STAT: 

LDFAIL: 

PRFAIL: 

SOFAIL: 

OUTSP; 

INSPEC: 

HANLOD: 



.CSISPC 

.DSTAT 

TST 

BNE 

.FETCH 

BCC 

.PRINT 

BR 

.FPRDT 

BCC 

.PRINT 

BR 

.SFDAT 

BCC 

.PRINT 
BR 
.EXIT 

.BLKW 
.NDRD 
.BLKW 
.ASCIZ 
.ASCIZ 
■.ASCIZ 
.EVEN 
.BLKW 
.BLKW 
.BLKW 
.END 



»OUTSP, SDEFEXT 

«STAT, "INSPEC 

STAT+a 

1» 

SINSPEC 

1$ 

SLOFAIL 

START 

sEMTBLK, »0, «INSPEC, 

2* 

SPRFAIL 

START 



iUse CSI to iex input filespec 

iCheck the device 

ito see if the handler is resident 

iBranch if it is 

!Dtheruiisei load that handler 

ioK 

iOtheruisei print load error message 

iand t ry asain 

«1 iMark file as protected 

iand b ranch if okay 

iDtheruise. print protect error message 

iand try a^ain 
sEMTBLK . »0 I sINSPEC. «0 iFinally. set current date 

iA date of means "use current system date" 
10$ iBranch if everything is okay 

sSDFAIL iOtheruiisei print date error message 

START iand t ry aSain 

iEverythinS okay - exit to KMON 



0,0,0.0 



iThe EMT argument block is built here 
iNo default extensions 
iBlock for .DSTATUS to use 



/Error in .LOAD request/ 
/Error in .FPRDT request/ 
/Error in .SFDAT request/ 



5»3 

1 

START 



iDutPut specs 9o here 

i Input specs do here 

iHandlers bedin loading here (if necessary) 



2.37 .GMCX (XM Only) 



The .GMCX request returns the mapping status of a specified window. 
Status is returned in the window definition block and can be used in a 
subsequent mapping operation. Since the .CRAW request permits combined 
window creation and mapping operations, entire windows can be changed 
by modifying certain fields of the window definition block. 
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The .GMCX request modifies the following fields of the window definition 
block: 

W.N APR base page address register of the window 

W.NBAS window virtual address 

W.NSIZ window size in 32-word blocks 

W.RID region identifier 

If the window whose status is requested is mapped to a region, the .GMCX 
request loads the following additional fields in the window definition block: 

W.NOFF offset value into the region 

W.NLEN length of the mapped window 

W.NSTS state of the WS.MAP bit is set to 1 in the window status 
word 

Otherwise, these locations are zeroed. 

Macro Call: .GMCX area[,addr] 

where: 

area is the address of a two- word EMT argument block 

addr is the address of the window definition block where the speci- 
fied window's status is returned 

Request Format: 

RO — > area: 



36 



addr 



Errors: 

Code 
3 
Example: 

Refer to the example for the .CRAW request. 



Explanation 

An illegal window identifier was specified. 



2.38 .GTIM 



.GTIM allows user programs to access the current time of day. The time is 
returned in two words and given in terms of clock ticks past midnight. 



Macro Call: 

where: 

area 
addr 



.GTIM area.addr 



is the address of a two-word EMT argument block 

is the address of the two-word area where the time is to be 
returned 
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Request Format: 



RO 



area: 



21 







addr 



The high-order time is returned in the first word, the low-order time in the 
second word. Your program must perform the conversion from clock ticks to 
hours, minutes, and seconds. 

The basic clock frequency (50 or 60 Hz) can be determined from the configu- 
ration word in the monitor (offset 300 relative to the start of the resident 
monitor). In the FB monitor, the time of day is automatically reset after 
24:00, when a .GTIM request is done and the date is changed if necessary. 
In the SJ monitor, the time of day is not reset unless SJ timer support was 
selected during the system generation process. The month is not automati- 
cally updated in either monitor. (Proper month and year rollover is a spe- 
cial feature that you enable through the system generation process.) 

The default clock rate is 60 cycles, that is, 60 ticks per second. Consult the 
RT-11 System Generation Guide if conversion to a 50-cycle rate is neces- 
sary. 

Because day rollover is done only through a .GTIM request, make sure that 
your program receives the correct time and day by issuing a .GTIM request 
before using the .DATE request. Nearly all RT-11 system utility programs 
issue a .GTIM request to make sure that rollover occurs daily. If you do not 
use a system utility program regularly, issue a .GTIM request at least once 
during a 24-hour period. 

NOTE 

There are also several SYSLIB routines that perform time 
conversion (see Chapter 3). They are CVTTIM, TIMASC, 
TIME, and SECNDS. 

Errors: 

None. 
Example: 

.TITLE GTIM. MAC 



.GTIM - This is an example in the use of the .GTIM request. 
This example is a subroutine that can be assembled separately 
and linked with a user proSram. 

CALLING SEQUENCE: CALL TIME 



INPUT: 
OUTPUT: 



Ra = Minutes in hi byte / hours in lo byte 
R5 = TioKs in hi byte / seconds in lo byte 
(in that order for ease of rewoual !) 



ERRORS: none possible 

NOTE: This example calls SYSLIB functions '*DIVTK' & '$DiySO' 



.GLOBL 
. MCALL 



tDIVTK .$DIVBO 
,GTIM 
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TIME! : 


Moy 


aTICKSiRl 






.GTIM 


• AREA.Rl 






Moy 


(R1)+.R0 






MOV 


@R1 iRl 






CALL 


*DiyTK 






Moy 


R3,R5 






SMAB 


R5 






CALL 


$DiyBO 






BISB 


R3,R5 






CALL 


»DIVBO 






Moy 


R3.Ra 






SUAB 


R4 






BISB 


Rl .Ra 






RETURN 






AREA: 


.BLKW 


2 




TICKS: 


.WORD 
.END 


0.0 


2.39 


.GTJB 







iRl points to where to put time 

iGet ticks since midnight uia .GTIM 

iRO = lo rde r time 

iRl = hi rde r t iwe 

iCall SYSLIB 32 bit diuide by clR f res 

iSaue t ioKs 

i Put them in hi byte 

iCall SYSLIB diuide by BO. routine 

iPut seconds in lo byte 

iDiuide by BO. onoe aSain 

i Put minutes in R4 

iMoue them to hi byte 

iPut hours in lo byte 

i and re t u rn 

iEMT a rSument area 

iTicks since midnight returned here 



The .GTJB request returns information about a job in the system. 

Macro Call: .GTJB area,addr[,jobblk] 

where: 

area is the address of a three-word EMT argument block 

addr is the address of an eight-word or twelve-word block into 
which the parameters are passed. The values returned are: 

Word 1 Job Number = priority level *2 (background job 
is 0; system jobs are 2, 4, 6, 10, 12, 14; and fore- 
ground job is 16 in system job monitors; back- 
ground job is and foreground job is 2 in FB and 
XM monitors; job number is in a SJ monitor) 

2 High-memory limit of job partition (highest loca- 
tion available to a job in low memory if the job 
executes a privileged .SETTOP #-2 request) 

3 Low-memory limit of job partition (first location) 

4 Pointer to I/O channel space 

5 Address of job's impure area in FB and XM moni- 
tors 

6 Low byte: unit number of job's console terminal 
(used only with multiterminal option; when 
multiterminal feature is not used) 

High byte: reserved for future use 

7 Virtual high limit for a job created with the 
linker /V option (XM only; when not running 
under the XM monitor or if /V option is not used) 

8-9 Reserved for future use 
10-12 ASCII logical job name (system job monitors 
only; contains zeroes for non-system jobs in FB 
and XM, not defined in SJ) 

jobblk is a pointer to a three-word ASCII logical job name for 
which data is being requested 
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Word 4 of addr, which describes where the I/O channel words begin, nor- 
mally indicates an address within the job's impure area. However, when a 
.CDFN is executed, the start of the I/O channel area changes to the user- 
specified area. 

Ifthejobhlk argument to the .GTJB request is between and 16 when the 
status of a job is requested, it is interpreted as a job number. If ih.e jobblk 
argument is 'ME', or equals -1, information about the current job is re- 
turned. If the jobblk argument is omitted, or equals -3 (a V03B-compatible 
parameter block), only eight words of information (corresponding to words 
1-8 of addr) are returned. 

In an F/B environment without the system job feature, you can get another 
job's status only by specifying its job number (0 or 2). 

Request Format: 



RO 



area: 



20 



addr 



jobblk 



Errors: 

Code Explanation 

No such job currently running. 
Example: 

See the program GTJB. MAC in the example listing. 

.TITLE GTJB. MAC 



.GTJB - This is an example of the .GTJB request. The 
example issues the request to determine if there is a loaded 
Foreground Job in the system. This program will execute properly 
with either a normal FB monitor or an FB monitor that includes 
System Job support. 



iFixed offset to SYSGEN word 
iSystem Job option bit 

iAssume FG Job number = 2 

iGet SYSGEN option word 

iSystem Job monitor? 

iBranoh if not 

ilf SOI FG Job number = IB 

iFind out if FG loaded 

iBranoh if no active FG Job 

innnOunce tnut rG job is loaded 

iand exit from program. 

JAnnounce that there's no FG Job 

iand exit from prosram. 

!EMT Arsument block 

iJob parameters passed back here 

iFG loaded messaSe 
iNo FG messase 





.MCALL 


.GVAL. .GTJB. .PRIh 




SYSGEN= 


372 




SYSJOB= 


40000 


START: 


MOy 


»2. Rl 




.GUAL 


«LIST, »SYSGEN 




BIT 


ttSYSJOB. RO 




BEO 


1* 




Moy 


»1B, Rl 


1$: 


.GTJB 


«LISTi »JOBARG. Rl 




BCS 


2$ 




.PRINT 


«FGLOAD 




.EXIT 




2$: 


.PRINT 
.EXIT 


«NOFG 


LIST: 


.BLKW 


3 


JDBARG: 


.BLKW 


12. 


FGLOAD: 


.ASCIZ 


/!FG Loaded! / 


NOFG: 


.ASCIZ 


/?No FG Job?/ 



.END 



START 
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2.40 .GTLIN 



The .GTLIN request collects a line of input from either the console terminal 
or an indirect command file, if one is active. This request is similar to 
.CSIGEN and .CSISPC in that it requires the USR, but no format checking 
is done on the input line. Because the .GTLIN command is implemented in 
the USR, the CSI will generate an error message if you attempt to input 
more than 80 characters to a .GTLIN request. Normally, .GTLIN collects a 
line of input from the console terminal and returns it in the buffer specified 
by you. However, if there is an indirect command file active, .GTLIN col- 
lects the line of input from the indirect command file just as though it were 
coming from the terminal. 

When bit 3 of the Job Status Word is set and your program encounters a 
CTRL/C in an indirect command file, the .GTLIN request collects subse- 
quent lines from the terminal. Note that if you then clear bit 3 of the Job 
Status Word, the next line collected by the .GTLIN request is the CTRL/C 
in the indirect command file; this causes the program to abort. Further 
input will come from the indirect command file, if there are any more lines 
in it. When bit 14 of the Job Status Word is set, the .GTLIN request passes 
lowercase letters. 

An optional prompt string argument (similar to the CSI asterisk) allows 
your program to query for input at the terminal. The prompt string argu- 
ment is an ASCIZ character string in the same format as that used by the 
.PRINT request. If input is from an indirect command file and the SET TT 
QUIET option is in effect, this prompt is suppressed. If SET TT QUIET is 
not in effect, the prompt is printed before the line is collected, regardless of 
whether the input comes from the terminal or an indirect file. The prompt 
appears only once. It is not reissued if an input line is canceled from the 
terminal by CTRL/U or multiple DELETE characters, unless the single- 
line editor is running. 

If your program requires a nonstandard command format, such as the user 
identification code (UIC) specification for FILEX, you can use the .GTLIN 
request to accept the command string input line. .GTLIN tracks indirect 
command files and your program can do a pre-pass of the input line to 
remove the nonstandard syntax before passing the edited line to .CSIGEN 
or .CSISPC. 

NOTE 

In an F/B environment, .GTLIN performs a temporary im- 
plicit uniocK Willie tue iine is ueing read from the console. 

Macro Call: .GTLIN linbufI,prompt][,type] 
where: 

linbuf is the address of the buffer to receive the input line. This 
area must be at least 81 bytes in length. The input line is 
stored in this area and is terminated with a zero byte 
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prompt is an optional argument and is the address of a prompt 
string to be printed on the console terminal. The prompt 
string has the same format as the argument of a .PRINT 
request. Usually, the prompt string ends with an octal 200 
byte to suppress printing the carriage return/line feed at 
the end of the prompt 

type is an optional argument which forces .GTLIN to take its 

input from the terminal rather than from an indirect file 

NOTE 

The only requests that can take their input from an indirect 
command file are .CSIGEN, .CSISPC, and .GTLIN. The 
.TTYIN and .TTINR requests cannot get characters from an 
indirect command file. They get their input from the console 
terminal (or from a BATCH file if BATCH is running). The 
.TTYIN and .TTINR requests and the .GTLIN request with 
the optional type argument are useful for information that is 
dynamic in nature — for example, when all files with a .MAC 
file type need to be deleted or when a disk needs to be initial- 
ized. In these circumstances, the response to a system query 
should be collected through a .TTYIN or a .GTLIN with the 
type argument so that confirmation can be done interactively, 
even though the process may have been invoked through an 
indirect command file. However, the response to the linker's 
Transfer Symbol? query would normally be collected through 
a .GTLIN, so that the LINK command could be invoked and 
the start address specified from an indirect file. Also, if there 
is no active indirect command file, .GTLIN simply collects an 
input line from the console terminal by using .TTYIN re- 
quests. 



Errors: 

None. 
Example: 



.TITLE GTLIN. MAC 

i + 

i .GTLIN - This 15 an example in the use of the .GTLIN request. 
i The example merely accepts input from the console terminal and 
i echoes it bacK> 



.MCALL 



, GTLIN. .PRINT. .EXIT 



START: 


.GTLIN 


SBUFF, 


SPROMT 


iGet a line of input from keyboard 




TSTB 


BUFF 






iNothinS entered? 




BEU 


1$ 






iBranoh if nothins entered 




.PRINT 


«BUFF 






iEcho the input baoK 




CLRB 


BUFF 






iClear first char of buffer 




BR 


START 






iGo baoK for more 


1$: 


.EXIT 








lExit program on null input 


BUFF: 


• BLKW 


ai. 






iBO character buffer (ASCIZ for .PRINT) 


PROMT: 


■ASCII 
.END 


/Ente r 
START 


some 


th 


in3>/<200> 
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2.41 .GVAL/.PVAL 



The .GVAL request returns in RO the contents of a monitor fixed offset; the 
.PVAL request changes the contents of a monitor offset. The .PVAL request 
also returns the old contents of an offset in RO to simplify saving and 
restoring an offset value. .GVAL and .PVAL must be used in an XM envi- 
ronment to read or change any fixed offset, and should be used with other 
RT-11 monitors for compatibility with XM and possible future releases of 
RT-11. 

Chapter 3 of the RT-11 Software Support Manual contains a table of the 
monitor's fixed offset locations. 



Macro Calls: 



where: 



area 
offset 



.GVAL area, offset 
.PVAL area, offset, value 

is the address of a two- or three- word EMT argument block 

is the displacement from the beginning of the resident moni- 
tor to the word to be returned in RO 



value is the new value to be placed in the fixed offset location 
Request Format for .GVAL: 
RO 



RO 



area: 


34 







offset 


lat for 


.PVAL: 


area: 


34 


2 




offset 




value 



Errors: 

Code 



Example: 



Explanation 

The offset requested is beyond the limits of the resident mon- 
itor. 



.TITLE .GyflL.MflC 



.cyflL - This is an example of the .GVAL request. It finds out 
if the foreground Job is actiue. Compare this example with the 
.GTJB example . 



.MCALL .GyftL. .PRINT. .EXIT 



CONFIG= 300 
FJOB*= 200 



■Offset in monitor of conf i Surat i on word 
iBit in oonfis word is on if FG aotiue 



2-60 Programmed Request Description and Examples 



START: 


.GUAL 


«AREA. ttCDNFIG 




BIT 


«FJOB$,RO 




BEO 


1* 




.PRINT 


SFGACT 




.EXIT 




1$: 


.PRINT 
.EXIT 


• NOFG 


ftREA: 


.BLKW 


Z 


FGACT! 


.ASCIZ 


/ ! FG is act i ue 


NOFG: 


.ASCIZ 

.ei;en 


/? No FG Job ?/ 



iGet monitor CONFIG word in RO 
iSee if FG Active bit is on 
»B ranch if not 
iAnnounce FG is active 
ithen exit program 
iAnnounce there's no FG Job 
ithen exit prosram 

iEMT arsument block 
! / iFG active messaSe 
iNo FG messase 



.END 



START 



.TITLE .PyAL.MAC 



. PyAL - This is an example of the .PVAL request. The example 
illustrates a way of ohansinS the default file size created 
by the .ENTER request. Compare this exainple with the .PEEK/. POKE 
example. . PWAL is used both to chanse the default file size and 
to read the old default file sizei returning the old ualue in RO. 



START: 



.MCALL .PVAL. .EXIT 



MAXBLK= 314 



.PyftL 

Moy 

.EXIT 



iMonitor offset of default file size 



EMTBLK: 


.BLKW 


3 


NENSIZ: 


.WORD 


100. 


OLDSIZ: 


.WORO 






SEMTBLK iSMAXBLK (SNEWSIZ iChanse default file size to 100. blocks 

RO » OLDSIZ iSaue the old default 

iWe'll Just exit now. but presumably 
iin a real proaram we'd do more 
iprooessinsi perhaps oreatins files 
iwith the new default size we Just 
iseti then before exitinS we'd restore 
ithe old default size. 



iEMT argument block 

iOld default size is saued here 



.END 



START 



2.42 .HERR/.SERR 



.HERR and .SERR are complementary requests used to govern monitor 
behavior for serious error conditions. During program execution, certain 
error conditions can arise that cause the executing program to be aborted 
(see Table 2-2). 

Normally, these errors cause program termination with one of the ?MON- 
F-error messages. However, in certain cases it is not feasible to abort the 
program because of these errors. For example, a multi-user program must 
be able to retain control and merely abort the user who generated the error. 
.SERR accomplishes this by inhibiting the monitor from aborting the job 
and causing an error return to the offending EMT. On return from that 
request, the carry bit is set and byte 52 contains a negative value indicat- 
ing the error condition that occurred. In some cases (such as the .LOOKUP 
and .ENTER requests), the .SERR request leaves channels open. It is your 
responsibility to perform .PURGE or .CLOSE requests for these channels, 
otherwise subsequent .LOOKUP/.ENTER requests will fail. 
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5 





4 






.HERR turns off user error interception. It allows the system to abort the 
job on fatal errors and generate an error message. (.HERR is the default 
case.) 

Macro Calls: .HERR 
.SERR 

Request Formats: 

.HERR Request RO = 
.SERR Request RO = 

Errors: 

Table 2-2 contains a list of the errors that are returned if soft error 
recovery is in effect. Traps to locations 4 and 10, floating-point excep- 
tion traps, and CTRL/C aborts are not inhibited. These errors have 
their own recovery mechanism. 

Table 2-2: Soft Error Codes (.SERR) 



Code Explanation 

-1 Called USR from completion routine. 

-2 No device handler; this operation needs one. 

-3 Error doing directory I/O. 

-4 .FETCH error. Either an I/O error occurred while the handler was being used, or 
an attempt was made to load the handler over USR or RMON. 

-5 Error reading an overlay. 

-6 No more room for files in the directory. 

-7 Invalid address (FB only); tried to perforin a monitor operation outside the job 
partition. 

-10 Invalid channel number; number is greater than actual number of channels that 
exist. 

-11 Invalid EMT; an invalid function code has been decoded. 

-12 Reserved for monitor internal use. 

-13 Reserved for monitor internal use. 

-14 Invalid directory. 

-15 Unloaded XM handler. 

-16 Reserved for monitor internal use. 

-17 Reserved for monitor internal use. 

-20 Reserved for monitor internal use. 

-21 Reserved for monitor internal use. 

-22 Reserved for monitor internal use. 
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Example: 



.TITLE HERR.MflC 
i + 

i .HERR / .SERR - This is an example in the use of the .HERR & .SERR 
! reiuestsi Normally fatal errors will cause a return to the user 
i program for prooessins and printinS of an appropriate error message. 



.MCALL 
.MCftLL 



.HERR I 
.EXIT. 



.SERR ..LOOKUP.. PURGE 
, PRINT. .CSISPC 



START: 



ERROR: 



FTLERR: 



.SERR 

.CSISPC 

.PURGE 

.LOOKUP 

BCS 

.HERR 

.PRINT 

.EXIT 

MOVB 

BMI 

.PRINT 

BR 

NEC 

DEC 

ASL 

MOV 

.PRINT 

BR 



SOUTSP.SDEFEXT 
«0 

»AREA.»0.»0UTSP+3B 
ERROR 

»LUPOK 

Sh52.ro 

FTLERR 

»NOFIL 

START 

RO 

RO 

RO 

TBL(RO) .RO 

START 



!Let prosram handle fatal errors 
iUse .CSISPC to Set filespeo 



SBranch if there was an error 
iNou permit '?MON-F-' errors. 
.Announce successful LOOKUP 
lExi t prosram 
iwas the error fatal? 
.Branch if yes 

iTry aSain ... 

.Make error « positiue 

.Adjust by one 

.Multiply by Z to maKe an index 

.Put message address into RO 

iand print it. 

.Go try some more errors 



TBL: 



M2: 

M3: 

M7: 

MIO: 

Mil: 

MIZ: 

M13: 

Mlfl: 

Ml?! 

Ml: 

M4: 

M5: 

MS: 

M15: 

M16: 

MZO: 

MZl: 

MZZ: 



Ml 
Ml 
M2 
M3 

na 

M5 

M6 

M7 

MIO 

Mil 

MIZ 

M13 

Mia 

M15 
MIS 
M17 
MZO 
MZl 
MZZ 

.ASCIZ 
.ASCIZ 
.ASCIZ 
.ASCIZ 
•ASCIZ 
.ASCIZ 
.ASCIZ 
■ASCIZ 
-ASCIZ 



.Table of Error Message Addresses 



iEr ro r Messages . . . 
/?Invalid Device -or- No Handler?/ 
/?Direotory I-O.Error?/ 
/?Address CheoK Error?/ 
/?Inual id Channel?/ 
/?Inualid EMT?/ 
/?Trap to 4?/ 
/?Trap to 10?/ 
/?Inualid directory?/ 
/?Memnpy pprnr'P/ 



.ASCIZ 



/?Not Possible?/ 



iNot possible in this prosram 

iNot possible in this prosram 

iNot possible in this prosram 

iNot possible in this proSram 

iNot possible in this proSram 

iNot possible in this prosram 

iNot possible in this proSram 

iNot possible in this prosram 

iNot Possible in this proSram 
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NOFIL: 


.ftSCIZ 


/?File Not Found?/ 


LUPOK: 


.ASCIZ 
.EVEN 


/Lookup succeeded/ 


AREA: 


.BLKW 


4 


DEFEXT: 


.WORD 


lO >0 lO 


DUTSP: 


.BLKN 


5»3 


INSPEC: 


.BLKW 


a*B 


HANLOD: 


.BLKW 


1 



iFix boundary 

iEMT Arsument blooK 

iNo default extensions 

iOutPUt specs So here 

i Input specs So here 

.Handlers besin loadinS here (if necessary) 



.END START 



2.43 .HRESET 

The .HRESET request stops all I/O transfers in progress for the issuing job, 
and then performs an .SRESET request. (.HRESET is not used to clear a 
hard-error condition.) In an SJ environment, a hardware RESET instruc- 
tion is used to terminate I/O. In an FB or XM environment, only the I/O 
associated with the job that issued the .HRESET is affected by entering 
active handlers at the abort entry point of the handler. All other transfers 
continue. 

Macro Call: .HRESET 

Errors: 

None. 
Example: 

Refer to the example for .SRESET for format. 

2.44 .INTEN 

.INTEN is used by interrupt service routines to: 

1. Notify the monitor that an interrupt has occurred and to switch to 
system state. 

2. Set the processor priority to the correct value. 

3. Save the contents of R4 and R5 before returning to the Interrupt Ser- 
vice Routine. Any other registers must be saved by you. 

.INTEN issues a subroutine call to the monitor and does not use an EMT 
instruction request. 

All external interrupts must cause the processor to go to priority level 7. 
.INTEN is used to lower the priority to the value at which the device should 

1 _ _^ ^ r\^ J JC. TXTrnTTIXT i-T J ■;«« ^« 4-^ •.«■». -.^4- »»•» U^ n^i^-Kri^^A r%i- 

Oe run. KJH rtJlUru IIUIU .xi'M x J^J-'N , mc ucvitc ixiociiu.pL ua.ii u<c oci ¥ ivcu, av 

which point the interrupt routine returns with an RTS PC. 

NOTE 

An RTI instruction does not return correctly from an inter- 
rupt routine that specifies an .INTEN. 

Macro Call: .INTEN prio[,pic] 
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where: 



pno 



pic 



is the processor priority at which to run the interrupt routine, 
normally the priority at which the device requests an inter- 
rupt 

is an optional argument that should be non-blank if the inter- 
rupt routine is written as a PIC (position-independent code) 
routine. Any interrupt routine written as a device handler 
must be a PIC routine and must specify this argument 



Errors: 

None. 
Example: 



.TITLE SLll.MflC 



SLll.MflC - This is an example in the use of the .INTEN request. 
The example is an in-line> interrupt seruioe routinei which may 
be assembled separately and linKed with a mainline program. 
The routine transfers data from a user specified buffer to a DLll 
Serial Line Interface. 



CALLING FORMAT: 





JSR 


R5.SL11 




.NORD 


wo rdcoun t 




.WORD 


BUFFER 


BUFFER: 


.BLKW 


wo rdcount 



.MCALL 



, INTEN 



DLWEC 


= 304 




DLCBR 


= 17S50a 




DLPRI 


= a 




5L11: : 


MOV 


(R5)+.(PC)+ 


WCNT: 


.WORD 







Moy 


(R5)+i(PC)+ 


BUFAD: 


.WORD 







ASL 


WCNT 




BEO 


1$ 




Moy 


«DLINT.@»DLyEC 




BIS 


»100.@«DLCSR 


1$: 


RETURN 




DLINT: 


.INTEN 


DLPRI. 




MOWB 


@BUFADi@«DLCSR+2 




INC 


BUFAD 




DEC 


WCNT 




BEO 


DLDUN 




RETURN 




DLDUN: 


BIC 

RETURN 

.END 


SIOO.SODLCSR 



ilnitiate Output 

;« words to t ransf e r 

iAddress of Data Buffer 



iDLl 1 Vector »♦♦ 
iDLl 1 Output CSR «»* 
iOLU Prio rity for RT-11 

iI/0 Initiation - Get word count 

iGet address of Data Buffer 

iMaKe word count byte count 
iJust leaMe if zero word count 
{Initialize DLll interrupt ueotor 
lEnable inte rrupts 
iRetu rn to caller 

{Interrupt seruice - Notify RT-11 

iand drop priority to that of DLll 

iTransf e r a byte 

!Bump buffer pointer 

iAll bytes transferred? 

SBranch if yes 

!No return from interrupt thru RT-11 

lAll done - disable DLll interrupts 
iReturn thru RT-1 1 



2.45 .LOCK/.UNLOCK 



.LOCK 

The .LOCK request keeps the USR in memory to provide any of its services 
required by your program. If all the conditions that cause swapping are 
satisfied, the part of the user program over which the USR swaps is written 
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into the system swap blocks (the file SWAP.SYS) and the USR is loaded. 
Otherwise, the copy of the USR in memory is used, and no swapping occurs. 
(Note that certain calls always require a fi-esh copy of the USR.) A .LOCK 
request always causes the USR to be loaded in memory if it is not already 
in memory. The USR is not released until an .UNLOCK request is given. 
(Note that under an FB monitor, calling the CSI or using a .GTLIN request 
can also perform an implicit and temporary .UNLOCK.) A program that 
has many USR requests to make can .LOCK the USR in memory, make all 
the requests, and then .UNLOCK the USR. 

In an FB environment, a .LOCK inhibits the other job from using the USR. 
Note that the .LOCK request reduces time spent in file handling by elimi- 
nating the swapping of the USR in and out of memory. .LOCK causes the 
USR to be read into memory or swapped into memory. After a .LOCK has 
been executed, an .UNLOCK request must be executed to release the USR 
from memory. The .LOCK/.UNLOCK requests are complementary and 
must be matched. That is, if three .LOCK requests are issued, at least three 
.UNLOCK requests must be done, otherwise the USR is not released. More 
.UNLOCK than .LOCK requests can be issued without error. 

Macro Call: .LOCK 

Notes: 

1. It is vital that the .LOCK call not come from within the area into which 
the USR will be swapped. If this should occur, the return from the 
.LOCK request would not be to the user program, but to the USR itself, 
since the .LOCK function inhibits the user program from being re-read. 
Also, none of the executable code should be in the area or reference 
anything in the area that the USR will occupy while it is locked. 

2. Once a .LOCK has been performed, it is not advisable for the program 
to destroy the area the USR is in, even if no further use of the USR is 
required, because this causes unpredictable results when an .UNLOCK 
is done. 

3. If a foreground job performs a .LOCK request while the background job 
owns the USR, foreground execution is suspended until the USR is 
available. In this case, it is possible for the background to lock out the 
foreground (see the .TLOCK request). 

Errors: 

None. 
Example: 

xveiei Lu Liie »x<iiiipm lur une .uimjU^JIV request. 
.UNLOCK 

The .UNLOCK request releases the User Service Routine (USR) from mem- 
ory if it was placed there with a .LOCK request. If the .LOCK required a 
swap, the .UNLOCK loads the user program back into memory. There is a 
.LOCK count. Each time the user does a .LOCK, the lock count is incre- 
mented. When the user does an .UNLOCK, the lock count is decremented. 
When the lock count goes to 0, the user program is swapped back in (see 
Note 1). 
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Macro Call: .UNLOCK 

Notes: 

1. The number of .UNLOCK requests must at least match the number of 
.LOCK requests that were issued. If more .LOCK requests are done, the 
USR remains locked in memory. Extra .UNLOCK requests in your pro- 
gram do no harm since they are ignored. 

2. With two running jobs in an FB environment use .LOCK/.UNLOCK 
pairs only where absolutely necessary. When a job locks the USR, the 
other job cannot use it until it is unlocked, which can degrade perform- 
ance in some cases. 

3. In an FB environment, calling the CSI with input coming from the 
console terminal results in an implicit (though temporary) .UNLOCK. 

4. Make sure that the .UNLOCK request is not in the area that the USR 
swaps into. Otherwise, the request can never be executed. 

Errors: 

None. 
Example: 

.TITLE LOCK. MAC 



.LOCK / .UNLOCK - This is an example in the use of the .LOCK and .UNLOCK 
requests. This example tries to obtain as much memory as possible (usinS 
the .SETTOP request) i uhich will force the USR into a swappins mode. The 
.LOCK request will brinS the USR into memory (over the hish ZK of our little 
program !) and force it to remain there until an .UNLOCK is issued. 



.MCflLL 
.MCftLL 



.LOCK (.UNLOCK ..LOOKUP 
.SETTOP. .PRINT. .EXIT 



START: 



Zi: 
1$: 



AREA: 
FILEl! 



FILE2: 



LMSG: 

FIFND: 

F2FND: 



SYSPTR=5a 



.SETTOP BSSYSPTR 
.LOCK 



.LOOKUP 

BCC 

.PRINT 

.EXIT 

.PRINT 

MOV 

INC 

May 

.LOOKUP 

BCS 
.PRINT 
.UNLOCK 
.EXIT 

.BLKW 

.RAD50 

.RAD50 

.RAD50 

.RAD50 

.RAD50 

.RAD50 

.ASCIZ 

.flSCIZ 

.ASCIZ 

.EVEN 

.END 



«AREA.«0.«FILE1 

1* 

«LMSG 

8F1FND 
SAREA.RO 
@R0 
»FILE2.2(R0) 



2$ 
SF2FND 



iPointer to besinninS of RMON 

iTry to allocate all of memory (up to RMON) 

ibrinS USR into memory 

iLODKUP a file on channel 

.Branch if successful 

iPrint Error MessaSe 

ithen exit prosram 

» Announce our success 

iRO => EMT Argument BlooK 

ilncrement low byte of Ist arS (ohan ») 

.Fill in pointer to new filespec 

iDo the .LOOKUP from filled in arS blocK 

.pointed to by RO. 

iBranoh on error 

iSay we found it 

inow release the USR 

Sand exit pros ram 



iEMT Arsument BlooK 

iA File we're sure to find 



.Another file we miJht find 



3 

/DK/ 

/PIP / 

/SAM/ 

/DK/ 

/TECO / 

/SAV/ 

/?Error on .LOOKUP?/ iError messaSe 

/. . .Found PIP. SAV/ 

/. . .Found TECO.SAy/ 

START 
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2.46 .LOOKUP 



A .LOOKUP request can be used in two different ways. The first way is to 
use the request as a standard lookup, which occurs under the SJ, FB, and 
XM monitors. The second way is to use the request when the system job 
feature is implemented. Both ways are described in this section. 

2.46.1 Standard Lookup 

The .LOOKUP request associates a specified channel with a device and 
existing file for the purpose of performing I/O operations. The channel used 
is then busy until one of the following requests is executed: 

.CLOSE 

.SAVESTATUS 

.SRESET 

.HRESET 

.PURGE 

.CSIGEN (if the channel is in the range 0-10 octal) 

Note that if the program is overlaid, channel 17(octal) is used by the over- 
lay handler and should not be modified. 

If the first word of the file name (the second word of dhlk) is and the 
device is a file-structured device, absolute block of the device is desig- 
nated as the beginning of the file. This technique is called a non-file-struc- 
tured .LOOKUP and allows I/O operations to access any physical block on 
the device. If a file name is specified for a device that is not file structured 
(such as LP:FILE.TYP), the name is ignored. 

The handler for the selected device must be in memory for a .LOOKUP. On 
return from the .LOOKUP, RO contains the length in blocks of the file just 
opened. On a return from a .LOOKUP for a non-directory, file-structured 
device (typically magtape), RO contains for the length. 

NOTE 

Care should be exercised when doing a non-file-structured 
.LOOKUP on a file-structured device, since if your program 
writes data, corruption of the device directory can occur and 
effectively destroy the disk. (The RT-11 directory starts in 
absolute block 6.) 

In particular, avoid doing a .LOOKUP or .ENTER with a file 
specification where the file value is missing. If the device 
type is not known in advance and is to be entered from the 
keyboard, include a dummy file name with the .LOOKUP or 
.ENTER, even when it is assumed that the device is always 
non-file structured. 

Macro Call: .LOOKUP area,chan,dblk[,seqnum] 
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where: 



area 



chan 
dblk 



seqnum 



is the address of a three-word EMT argument block 

is a channel number in the range 0-377(octal) 

is the address of a four-word Radix-50 descriptor of the 
file to be operated upon 

is a file number for magtape and cassette 

If this argument is blank, a value of is assumed. 

For magtape, it describes a file sequence number. The ac- 
tion taken depends on whether the file name is given or is 
null. The sequence number can have the following values: 

-1 means suppress rewind and search for a file name 
from the current tape position. If a file name is given, 
a file-structured lookup is performed (do not rewind). 
It is important that only -1 be specified and not any 
other negative number. If the file name is null, a non- 
file-structured lookup is done (tape is not moved). 

means rewind to the beginning of the tape and do a 
non-file-structured lookup. 

where n is any positive number. This means position 
the tape at file sequence number n and check that the 
file names match. If the file names do not match, an 
error is generated. If the file name is null, a file-struc- 
tured lookup is done on the file designated by seqnum. 







n 



Request Format 
RO 



area: 



chan 



dblk 



seqnum 



Errors: 



Code Explanation 

Channel already open. 

1 File indicated was not found on the device. 



Example: 



.TITLE LOOKUP. MAC 



iLOOKUP - This is an eKample in the use of the .LOOKUP request. 
This example determines whether or not the RT-11 Deuice Oueue 
WorKfile exists on device DK : and if so i prints its size in 
blooKs on the console terminal. 
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.MCALL 


.LOOKUP, .PRINT.. 


STftRT: 


.LOOKUP 


«AREA,«0,«OUSPEC 




BCC 


1$ 




.PRINT 


aNOFIL 




.EXIT 




1$: 


Moy 


SSIZE.RI 




CALL 


CNVIO 




.PRINT 


sBUFF 




.EXIT 




CNUIO: 


Moy 


RO.-(SP) 




CLR 


RO 


1*! 


INC 


RO 




SUB 


«10. iSSP 




BGE 


1* 




ADD 


«72,eSP 




DEC 


RO 




BEO 


2* 




CALL 


CNVIO 


Zt: 


MOUB 
RETURN 


(SP)+,(R1)+ 


AREA: 


.BLKW 


3 


OUSPEC: 


.RADSO 


/DK OUFILE/ 




.RAD50 


/TMP/ 


BUFF: 


.ASCII 


/DK:OUFILE.TMP = 


SIZE: 


.ASCIZ 


/ Blocks/ 


NDFIL: 


.ASCIZ 
.EVEN 


/?Fi le Not Found 




• END 


START 



See if there's a DK : OUFILE . TMP 
Branch if there is 
Print 'File Not Found' messaSe 
then exit pros ram 
Rl => uhere tc put ASCII size 
Convert size (in RO) to ASCII 
Print size of OUFILE. TMP on console 
then exit proSram 

Subroutine to convert Binary « in RO 
to Decimal ASCII by repetitiue 
subtraction. The remainder for each 
radix is made into ASCII and pushed 
on the stacKi then the routine calls 
itself. The code at 2* pops the ASCII 
disits off the staoK and into the out- 
put buffer, euentuallv returning to 
the callins prosram. This is a MERY 
useful routine, is short and is 
memory efficient. 

iEMT Argument BlooK 



2.46.2 System Job Lookup 

The foreground and background jobs can send messages to each other via 
the existing .SDAT/.RCVD/.MWAIT facihty. A more general message facil- 
ity is available to all jobs through the message queue (MQ) handler. By 
turning message handling into a formal "device" handler, and treating 
messages as I/O to jobs, the existing .READ/C/W-.WRITE/C/W-.WAIT 
mechanism can be used to transmit messages. A channel is opened to a job 
via a .LOOKUP request, after which standard I/O requests are issued to 
that channel. 

Macro Call: .LOOKUP area,chanJobdes 

where: 

area is the address of a two-word EMT argument block 

chan is the number of the channel to open 

jobdes is the address of a four-word descriptor of the job to which 
messages will be sent or received 

jobdes -^ .RAD50 /MQ/ 

.ASCII /logical-job-name/ 

where logical-job-name can be from one to six characters 
long. It must be padded with nulls if less than six characters 
long. If logical-job -name is zero, the channel will be opened 
for .READ/C/W requests only and such requests will accept 
messages from any job 



2-70 Programmed Request Description and Examples 



Request Format: 
RO —> area: 



chan 



jobdes 



The .LOOKUP request associates a channel with a specified job for the 
purposes of sending inter-task messages. RO is undefined on return from 
the .LOOKUP. 



Errors: 




Code 


Explanation 





Channel already open. 


1 


No such job. 


Example: 




■TITLE SJLOOK.MAC 



•LOOKUP - This is an example in the use of the .LOOKUP request 
to open a messaae channel to a System Job. specifically, the 
RT-11 Device Queue ForeSround prosram. NOTE: This example assumes 
it will be run under an FB Monitor Generated with System Job 
Support and that QUEUE. REL has been successfully FRUN/SRUN ! ! ! 





.MCALL 


.LOOKUP. 


PRINT 


..EXIT 


..WRITW. .READW 


START: 


.LOOKUP 


»AREA.«0 


.«QMSG 




iTry to open a channel to QUEUE 




BCC 


1$ 






.Branch if successful 




.PRINT 


SNOJOB 






lEr ro r ... print error messase 




.EXIT 








i then exit p rosram 


1$: 


.WRITW 


»AREAi«0 


.»RMSG 


.«G 


iSend a meaningless messaSe to QUEUE 




BCS 


2$ 






!Branch if error 




.READW 


»AREA.»0 


.«RMSG 


.»B 


iWait for an aoKnouledSment message 




BCS 


2t 






.Branch if error 




.PRINT 


»ORUN 






.Announce QUEUE aliue and well 




.EXIT 








iThen exit 


2$: 


.PRINT 
.EXIT 


»MSGERR 






.Print error messase 
iThen exit 


AREA: 


.BLKM 


5 






iEMT Argument Block 


OMSG: 


.RAD50 
.ASCIZ 
.WORD 


/MQ/ 

/QUEUE/ 

0.0 






iJob Descriptor BlocK for .LOOKUP 


RMSG: 


.WORD 
.ASCII 



/SJLOOK/ 






iOummy message .. . 


MSGERR: 


.ASCIZ 


/?Messa9e Error 


?/ 


.Error Messages, etc. 


NO JOB: 


.ASCIZ 


/70UEUE is not 


runninS?/ 


QRUN: 


.ASCIZ 


/! QUEUE 


is al iue and 


running ! / 




.EVEN 












.END 


START 









2.47 MAP {XM Only) 



The .MAP request maps a previously defined address window into a dy- 
namic region of extended memory or into the static region in the lower 28K 
words of memory. If the window is already mapped to another region, an 
implicit unmapping operation is performed (see the .UNMAP programmed 
request). 
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Macro Call: 

where: 

area 
addr 



.MAP area[,addr] 



is the address of a two-word EMT argument block 

is the address of the window definition block containing a 
description of the window to be mapped and the region to 
which it will map 



Request Format: 
RO 



area: 



36 I 4 



addr 



Errors: 



Code 

2 
3 

4 



Explanation 

An invalid region identifier was specified. 

An invalid window identifier was specified. 

The specified window was not mapped because the offset is 
beyond the end of the region, the region is larger than the 
window, or the window would extend beyond the bounds of 
the region. 

Example: 

Refer to example for the .CRAW request. 



2.48 MfPS/MTPS 



The .MFPS and .MTPS macro calls allow processor-independent user access 
to the processor status word. The contents of the registers are preserved 
across either call. 

The .MFPS call is used to read the priority bits only. Condition codes are 
destroyed during the call and must be directly accessed (using conditional 
branch instructions) if they are to be read in a processor-independent 
manner. 

In the XM monitor, .MFPS and .MTPS can be used only by privileged jobs 
and are not available for use by virtual jobs. 

Macro Call: .MFPS addr 

where: 

addr is the address into which the processor status is to be stored; 
if addr is not present, the value is returned on the stack. Note 
that only the priority bits are significant 

The .MTPS call is used to set the priority bits. 

Macro Call: .MTPS value 
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where: 



value is either the value or the address of the value (depending on 
addressing mode) to be placed in the PSW. If value is not 
present, the processor status word is taken from the stack. 
Note that the high byte on the stack is set to when value is 
present. If value is not present, you should set the stack to 
the appropriate value. In either case, the lower byte on the 
stack is put in the processor status word 

Note: 

It is possible to perform MTPS and MFPS operations and access the condi- 
tion codes by following this special technique: 

1. In the beginning of your program, set up the lOT trap vector as 
follows: 



= 20 



.ASECT 

.WORD 
.WORD 



GETPS 
340 



iSET UP lOT 

ilOT BERUICE ADDRESS IN 'MFPS' SUBROUTINE 
i PRIORITY 7 



2. Elsewhere in your program place the following routines: 

i + 

i MFPS/MTPS ROUTINES . . . 



MFPS: 



lOT 



iEXECUTE lOT 

iWILL RETURN TO CALLER W/ PS ON STACK 



GETPS! 


MQi.' 


a(SP) ,@SP 




MO",' 


2(SP) ,4(SP) 


MTPS: 


RTI 





iPUT USER RETURN ON TOP 

iMO^E PS SAVED BY IDT 

iWILL RETURN TO CALLER W/ NEW PS 



3. To get the PSW or to set the PSW to a desired value, follow this 
sequence of instructions: 



! + 

i TO GET PS 



JSR 



PC. MFPS 



iGET PS 

iCONTINUE, PS IS ON STACK . . . 



i TO PUT PS 



MOV NEWPS.-(SP) 
JSR PC. MTPS 



iPUT DESIRED PS ON STACK . . . 

iCALL MTSP 

iCONTINUE PROCESS W/ NEW PS . . . 



Errors: 



None. 
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Example: 



.TITLE MFPS 



i .MFPS / .MTPS - This is an example in the use of the .MFPS and .MTPS 
i requests. The example is a sKeleton mainline program uhioh calls a 
i subroutine to set the next free element in an RTll-liKe linKed sueue. 





.MCflLL 

jsw = aa 


.MFPS. .MTPS 1. 




TTSPC* = 


10000 


START: 








BIS 


•TTSPCt .e«jsw 




CALL 


GETOUE 




BCC 


1$ 




.PRINT 


bNOELEM 




BIC 


oTTSPC*.B«JSW 




.EXIT 




1$: 


NOP 
NOP 






.PRINT 


ttGOTl 


2$: 


.TTINR 






BCS 


2« 




BR 


START 


GETOUE: 


Moy 


«0HEAD.R4 




TST 


SRa 




BEO 


11$ 




.MFPS 






.MTP5 


»3a0 




Moy 


@RaiR5 




Moy 


eRs.sRa 




.MTPS 






TST 


(PC) + 


11$: 


SEC 
RETURN 




OHEAD: 


.WORD 01 




Ql: 


.WORD 02 


.0.0 


02; 


.WORD 03 


,0.0 


03: 


.WORD 0, 


0,0 


NDELEM; 


.flSCIZ 


/?No, mo re Ouei 


GOTl: 


.flSCIZ 


/Element ac=iu 



.PRINT, .TTINR 
iJob Status Word location 
iTTY Special bit 

iSKeleton mainline proSram. 
iSet TTY Special bit 



iCall subroutine to return next free 

ielement - on return R5 => element 

iBranoh if no error 

;No more elements auailable 

iReset special bit 

lExi t p rosram 

iPrcSram continues 

! 

iAnnounce success 

iWait for a Key to be hit on console 



! Point to queue head 

iOueue exhausted? 

!Ye5...set error on leauinS 

iSaue status on stack 

iRaise priority to 7 

iR5 points to next element 

iRe 1 inK the queue 

iRestore preuious status 

iThis clears carry & sKips next instruction 

iSet carry bit (to flaS error) 

iReturn to caller 

iOueue head 

i3 linKed queue elements 



.END 



START 



2.49 MBKJ (FB and XM; SJ Monitor Special Feature) 

The .MRKT request schedules a completion routine to be entered after a 
specified time interval (measured in clock ticks) has elapsed. The .MRKT 
request is an optional feature in the SJ monitor, and is selected as a system 
generation option. 

A .MRKT request requires a queue element taken from the same list as the 
I/O queue elements. The element is in use until either the completion rou- 
tine is entered or a cancel mark time request is issued (see .CMKT request). 
The user should allocate enough queue elements to handle at least as many 
mark time and I/O requests as are expected to be pending simultaneously. 
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Macro Call: .MRKT area,tiine,crtn,id 
where: 

area is the address of a four-word EMT argument block 

time is the address of a two word-block containing the time inter- 
val (high order first, low order second), specified as a number 
of clock ticks 

crtn is the entry point of a completion routine 



id 



is a non-zero number or memory address assigned by the user 
to identify the particular request to the completion routine 
and to any cancel mark time requests. The number must not 
be within the range 177700-177777, which is reserved for 
system use. The number need not be unique (several .MRKT 
requests can specify the same id). On entry to the completion 
routine, the id number is in RO 



Request Format: 



RO 



area: 



22 1 





time 


crtn 




id 



Errors: 

Code Explanation 

No queue element was available. 

Example: 

.TITLE TREAD. MAC 



i .MRKT/.CMKT - This is an example in the use of the .MRKT/.CMKT re^iuests 
i The eKample illustrates a user impletnented "Timed Read" to cancel an 
i input request after a specified time interval. 



START! 
1$: 



Z$! 



.MCALL 



LF = 12 

jsw = aa 



.MRKT . .TTINR , .EXIT ,. PRINT , .TTYOUT , .CMKT . . TWAIT . . DSET 



TCBIT* = 100 iReturn C-bit bit in JSW 



iLine Feed 

iJob Status Word location 



TTSPC* = 10000 



.OSET 

MOM 

MOV 

CALL 

5CS 

.PRINT 

BR 

.PRINT 

.EXIT 

i* TREAD 

i* Input 

i* 

i* OutPU 



SXOUE.BI 
•PROMT. RO 
• BUFFR.Rl 
TREAD* 
Z* 

SLINE 
1$ 
STIMOUT 



iTTY Special Mode bit in JSW 

iNeed an extra U-Elem for this 

jMainlins - RO => Prowpt 

iRl => Input buf f e r 

iDo a "timed read" 

iC-bit set = Timed out 

■"Process" data... 

iGo bacK for more 

iRead timed out - could process 

ipartial data but we'll Just exit 



* - "Timed Read" Subroutine 

RO => Prompt Strins / RO = if no prompt 

Rl => Input Buf f e r 
t: Buffer contains input charsi if any > terminated 

by a null char. C-Bit set if timed out 
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TREAD*! 


TST 


RO 




BEO 


1$ 




.PRINT 




1$: 


CLR 


TBYT 




■ MRKT 


STAREA .«TIME .»TOUT .«1 




BIS 


«TCBIT*.e«JSW 




CLRB 


@R1 


TTIN: 


.TWAIT 
.TTINR 


»AREA 




BIT 


«1 .(PC) + 


TBYT! 


.NORD 







BNE 


2* 




BCS 


TTIN 




MOyB 


R0.(R1)+ 




.CMKT 


«TAREA.«0 


2$: 


BIS 


«TTSPC*.B»JSW 


3*: 


.TTINR 






MOVB 


R0.(R1)+ 




BCC 


3$ 




CLRB 


-(Rl) 




BIC 


«TCBIT*!TTSPC*.@«JSW 




ROR 


TBYT 




RETURN 




TOUT: 


INC 
RETURN 


TBYT 


XOUE: 


.BLKW 


10. 


ftREft! 


.NORO 


O.WAIT 


TflREA: 


.BLKW 


a 


TIME: 


.WORD 


O.GOO. 


WAIT: 


.WORD 


0,1 


LINE! 


.ASCII 


/Not in stock - Part « 


BUFFR: 


.BLKB 


Bl. 


PROMT: 


.ASCIZ 


/Enter Part « >/<Z00> 


TIMOUT: 


.ASCIZ 


/Timed read expired!/ 




.END 


START 



See if we haue to prompt 

Branch if no . . . 

Output prompt 

Clear t ime-out f laS 

Issue if .MRKT for 10 sec 

Set C-Bit bit in JSW (for F/B) 

Start with "empty" buffer 

Wait so ue don't locK out BG 

LooK for a character 

Timed out? 

Time-out f 1 as 

Branch if yes 

Branch if input not complete 

Xfer 1st cha racte r 

Cancel .MRKT 

Turn on TT: Special mode 

Flush TT: rinS buf f e r 

puttini characters in user buffer 

If more ohar> So 9et 'em 

Terminate input with null byte 

Clear bits in JSW 

Set carry if timed out 

Return to caller 



iLeaue completion code 
iExt ra 0-Element 
iEMT Argument blooK for .TWAIT 
!EMT ArSument blooK for .MRKT 
iTime-out interual (10 sec) 
il/BO SCO uait between .TTINRs 
/ iDummy response 
iUsB r input buffer 
iPrompt 
iToo bad message 



2.50 .MTATCH (Special Feature) 

The .MTATCH request attaches a terminal for exclusive use by the re- 
questing job. This operation must be performed before any job can use a 
terminal with multiterminal programmed requests, although a job can is- 
sue a .MTGET request before a .MTATCH. If .MTATCH request fails be- 
cause the terminal is owned by another job, the job number of the owner is 
returned in RO. 

Macro Call: .MTATCH area,addr,unit 

where: 



area 



addr 



unit 



is the address of a three-word EMT argument block 

is the optional address of an asynchronous terminal status 
word, or it must be #0 (The asynchronous terminal status 
word is a special feature that you can select during the sys- 
tem generation process.) 

is the logical unit number of the terminal (The logical unit 
number is the number assigned by the system to a particular 
physical unit during the system generation process.) 



Request Format: 
RO -^ area: 



37 


5 


addr 





unit 
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Errors: 



Code 

2 
3 
4 
5 

Example: 



Explanation 

Nonexistent logical unit number. 

Invalid request; function code out of range. 

Unit attached by another job (job number returned in RO). 

In the XM monitor, the optional status word address is not 
in valid user virtual address space. 



MTXAMP.MAC - The follouins is an example proSram that 
demonstrates the use of the mul t i te rminal 
prosrammed requests. The prosram attaches all the 
terminals on a siuen systernt then proceeds with an 
input/eoho exercise on all attached terminals until 
CTRL/C is sent to it . 



.MCALL 


.MTATCH 


.MTPRNT. 


.MTGET 


..MTIN..MTOUT 


.MCALL 


.PRINT.. 


MTRCTO.. 


1TSET. 


.MTSTAT. .EXIT 


HNGUP* 


= nooo 






.Terminal off-line bit 


TTSPC$ 


= 10000 






.Spec i al mode bit 


TTLC* 


= 40000 






.Lower-case mode bit 


AS.INP 


= 40000 






.Input available bit 


M.TSTS 


= 






.Terminal status word 


M.TSTW 


= 7 






.Terminal state byte 


M.NLUN 


= a 






i» of LUNs word 


MTXAMP: 








.Start of pros ram 




.MTSTAT 


«MTA.»MSTAT 


iGet MTTY status 




MOy 


MBTAT+M 


.NLUN.R4 iR4 = « LUNs 




BEQ 


MERR 




.None? Not MTTY! ! ! 




CLR 


Rl 




.Initial LUN = «0 




MOV 


»AST.R2 




.R2 -» AST word array 


10$: 


•MTATCH 


«MTA.R2 


.Rl 


.Attach te rminal 




BCC 


20* 




iSuccess ! 




CURB 


TAKRl) 




.Set attach failed 




BR 


30* 




.Proceed with next LUN 


20*; 


MOVB 


»1 .TAKRl) 


.Attach successful 




Moy 


Rl .R3 




iCopy LUN 




ASL 


R3 




.Multiply by 8 for offset 




ASL 


R3 




.to the terminal status 




ASL 


R3 




iblocK. . . 




ADD 


•TSB.R3 




!R3 -^ LUN's TSB 




.MTGET 


#MTA.R3 


)R1 


.Get LUN's status 




BIS 


»TTSPC*+TTLC* 


M.TSTSvRj) iSet special 










imode and lower case 




•MTSET 


«MTA.R3 


iRl 


iSet LUN's status 




BITB 


»HNGUP*/400.M 


TSTW(R3) iOn line? 




BNE 


30* 




iNope! 




.MTRCTO 


»MTA.R1 




.Reset CTRL/0 




.MTPRNT 


ttMTA.»HELLO.RJ 


5Say hello. , . 


30*: 


ADD 


«2.R2 




iR2 -* Next AST word 




INC 


Rl 




iGet next LUN 




CMP 


Rl .R4 




.Done? 




BLO 


10* 




.Nope. 30 attach another 
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LOOP: 



10$: 



20$: 



CLR 

MOV 

TSTB 

BEO 

BIT 

BEO 

.MTIN 

BCS 

.MTOUT 

BCS 

ADD 

INC 

CMP 

BLO 

BR 



ERR: 
MERR; 

AST; 
TAI; 



MSTAT: 
TSB: 

MTA: 
MTCHAR: 

HELLO: 

NOMTTY: 
UNEXP! 



.BLKW 
.BLKB 



.BLKW 
.BLKW 

.BLKW 
.BYTE 

.ASCII 
.ASCIZ 
.ASCIZ 
.ASCIZ 

.END 



Rl 

«AST ,R2 

TAI (Rl ) 

20* 

»AS.INP .(R2) 

20* 



ilnput & echo forever 
ilnitial LUN = 
iRZ -^ AST wo rds 
iTerminal attached? 
iNope . . . 
iAny input? 
iNope . . . 



«MTA i«tMTCHAR iRl t«l ilnput a character 



.PRINT 

.EXIT 

.PRINT »NOMTTY 

.EXIT 



ERR 

«MTAt«MTCHAR .Rl .»1 

ERR 

«2.R2 

Rl 

Rl .R4 

10* 

LOOP 

»»UNEXP 



16. 

16. 



S. 

16. »4, 



iOoops! Error on input 
iEoho the charact e r 
iOoops! Error on output 
iPoint to next AST word 
iGet next LUN 
iDone them all? 
;No f ^0 checK another 
iYes I repeat (forever!) 

lUnexpected error... 
iPrint messaJe & exit! 
iNot Multiterminal 
iPrint messaSe & exit 

i Asynch ronous Terminal 
iStatus Words (1/LUN) 
iTerminal attached list 
!1 Byte per LUN. . . 
iO = Not attached 
iMTTY status blocK 
iTerminal status blocks 
;16. blocKs of 4 wo rds 
iEMT arSument blocK 
iCharaoter stored here 



<33>"H"<33>"J" igT52 Home + Erase to EOS 
/Hello! Characters typed will be echoed/ 
/?Not multiterminal system?/ 
/?Unexpected e r ro r . . . p ro S ram aborting?/ 



MTXAMP 



iEnd of pros ram 



2.S1 .MTDTCH (Special Feature) 

The .MTDTCH request detaches a terminal from one job and makes it 
available for other jobs. When a terminal is detached, it is deactivated, and 
unsolicited interrupts are ignored. Input is disabled immediately, but any 
characters in the output buffer are printed. Attempts to detach a terminal 
attached by another job result in an error. 

Macro Call: .MTDTCH area,unit 

where: 



area is the address ot a tnree-word iiivi'i' argument biocK 
unit is the logical unit number (lun) of the terminal to be detached 
Request Format: 
RO — > area: 



37 6 


unused 


— unit 
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Errors: 

Code 

1 

2 

3 

Example: 



Explanation 

Invalid unit number, unit not attached. 

Nonexistent logical unit number. 

Invalid request; function code out of range. 



.MCALL .MTDTCHi.MTPRNT . . MTATCH . . EXIT ..PRINT 



START: 





.MTATCH »MTA.«0.«3 


iATTACH TO LUN 3 




BCS 1$ 


iATTACH ERROR 




.MTPRNT MTA.»MESS»»3 


iPRINT MESSAGE 




.MTDTCH ttMTA .«3 


iOETACH LUN 3 




.EXIT 




1$; 


.PRINT ttATTERR 
.EXIT 


iATTACH ERROR 

; (PRINTED ON CONSOLE) 


ATTERR: 


.ASCIZ/ATTACH ERROR/ 




MESS: 


.ASCIZ/DETACHING TERMINAL/ 
.EVEN 




MTA: 


.BLKW 3 
.END START 





2.52 .MTGET (Special Feature) 

The .MTGET request returns the status of the specified terminal unit to the 
caller. If a .MTGET request fails because the terminal is ovsrned by another 
job, the job number of the owner is returned in RO. You do not need to do an 
.MTATCH before using the .MTGET request. 

Macro Call: .MTGET area,addr,unit 

where: 

area is the address of a three-word EMT argument block 

addr is the address of a four-word status block where the status 
information is returned 

unit is the logical unit number (lun) of the terminal whose status 
is requested. A unit need not be attached to the job issuing a 
.MTGET request. If the unit is attached to another job (error 

-~>J« A\ +1-.^ 4-,^«~,;««i ^j-„-(-,,„ ..,;n i 4. i i xi. _ ^_i 

vyuuc Tj, i;a.ic i.ciiiJ.iiioi.1 ai/atu.a will uc ICLUlllCU iXWJ. Lilt; JUL) num- 
ber will be contained in RO. In any other error condition, the 
contents of RO are undefined 

Request Format: 

RO — > area: 



37 1 


addr 


— I unit 
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The status block has the following structure: 
addr-» 



M.TSTS 



M.TST2 



M.FCNT 



M.TSTW 



M.TFIL 



M.TWID 



The following information is contained in the status block: 
Byte Offset 




2 

4 
5 
6 

7 



(M.TSTS) 

(M.TST2) 

(M.TFIL) 

(M.FCNT) 

(M.TWID) 

(M.TSTW) 



Description 

Terminal configuration word 1 
Terminal configuration word 2 
Character requiring fillers 
Number of fillers 
Carriage width 
Terminal status byte 

Note that if an error occurs, and the error code is not 1 or 4, the status block 
will not have been modified. 

NOTE 

Use the Bit Set (BIS) and Bit Clear (BIC) instructions in- 
stead of Move (MOV) and Clear (CLRJ instructions when set- 
ting terminal and line characteristics. This avoids changing 
other bits inadvertently. 

The bit definitions for terminal configuration word 1 (M.TSTS) are as fol- 
lows: 

Meaning 

Terminal has hardware tab 
Output RET/LF when carriage width exceeded 
Terminal has hardware form feed 
Process CTRL/F and CTRL/B (and CTRL/X if system 
job) as special command characters (if clear, CTRL/F 
and CTRL/B are treated as ordinary characters) 
Inhibit TT wait (similar to bit 6 in the Job Status Word) 
Enable CTRL/S-CTRL/Q processing 
Line speed (baud rate) mask. Bits 8 through 11 indicate 
the terminal baud rate (DZll and DZVll only). The val- 
ues are as follows: 

Octal Value of 
Line Speed Mask 



Value 


Bit 


1 





2 


1 


4 


2 


10 


3 


100 


6 


200 


7 


7400 


8-11 



\S bits 11-8) 


Baud Rate 


0000 


50 


0400 


75 


1000 


110 


1400 


134.5 


2000 


150 


2400 


300 


3000 


600 


3400 


1200 
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4000 1800 

4400 2000 

5000 2400 

5400 3600 

6000 4800 

6400 7200 

7000 9600 

7400 (unused) 

Character mode input (similar to bit 12 in the Job 

Status Word) 

Terminal is remote (Read-only bit) 

Lowercase to uppercase conversion disabled 

Use backspace for rubout (video type display) 

The bit definitions for terminal configuration word 2 (M.TST2) are as fol- 
lows: 



10000 12 



20000 
40000 
100000 



13 
14 
15 



Value 
3 



10 

20 

140 

200 

77400 

100000 



0-1 



3 
4 
5-6 

7 

8-14 

15 



Meaning 

Character length, which can be 5(00), 6(01), 7(10), or 

8(11) bits (DZ only) 

Unit stop, which sends one stop bit when clear, two stop 

bits when set (DZ only) 

Parity enable (DZ only) 

Odd parity when set; even parity when clear 

Reserved 

Read pass all 

Reserved 

Write pass all 



The bit definitions for terminal status byte (M.TSTW) are as follows: 



Value 

2000 

4000 

10000 

40000 



Bit 
10 
11 
12 
14 



100000 
Errors: 

Code 
1 



15 



Meaning 

Terminal is shared console 

Terminal has hung up 

Terminal interface is DZll 

Double CTRL/C was struck (the .MTGET request resets 

this bit in the terminal control block if it is on) 

Terminal is acting as console 



Explanation 

Invalid unit number, unit not attached. 
Nonexistent logical unit number. 



3 
4 
5 



Invalid request; function code out of range. 

Unit attached by another job (job number returned in RO). 

In the XM monitor, the status block address is not in valid 
user virtual address space. 

Example: 

Refer to the example for the .MTATCH request. 
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2.53 .MTIN (Special Feature) 



UO----- 



c^ fS Arts 



C Sii Codi 



The .MTIN request reads characters from the keyboard buffer. It is the 
multiterminal form of the .TTYIN request. The .MTIN request moves one 
or more characters from the input ring buffer to a buffer specified by you. 
The terminal must be attached. An updated user buffer address is returned 
in RO if the request is successful. If bit 6 is set in the M.TSTS word (see the 
MTSET request), the .MTIN request returns immediately with the carry 
bit set (code 0) if there is no input available. Operation is similar for the 
system console if bit 6 is set in the JSW. If bit 12 in M.TSTS is clear, no line 
is available; if bit 12 is set, there are no characters in the buffer. If these 
conditions do not exist, the .MTIN request waits until input is available, 
and the job is suspended until input is available. 

The meaning of bits 6 and 12 in the terminal configuration word (M.TSTS) 
for the programmed request .MTIN is as follows: 



Meaning 

Normal mode of input (echo provided); wait for line 

Carry bit set: no line available 

Carry bit set: no character available; no echo provided 



Bite 


Bit 12 








1 





1 


l'"'-'N 





1 



No echo provided 

If a multiple-character request was made and the number of characters 
requested are not available, the request can either wait for the characters 
to become available, or it can return with a partial transfer. If bit 6 of 
M.TSTS is clear, the request waits for more characters. If bit 6 is set, the 
request returns with a partial transffer. In the latter case, RO contains the 
updated buffer address (pointing past the last character transferred), the C 
bit is set, and the error code is 0. 

The .MTIN request has the following form: 

Macro Call: .MTIN area,addr,unit[,chrcnt] 

where: 

area is the address of a three-word EMT argument block 

addr is the byte address of the user buffer 

unit is the logical unit number of the terminal input 

chrcnt is a character count indicating the number of characters to 
transfer. The valid range is from 1 to 255(decimal). A char- 
acter count of zero means one character 

Request Format: 

RO -^ area: 



37 2 


addr 


chrcnt unit 
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Errors: 



Code 


1 
2 
3 
5 



Explanation 

No input available — bit 6 is set in the Job Status Word (for 
the system console) or in M.TSTS by the .MTSET request. 

Invalid unit number, unit not attached. 

Nonexistent logical unit number. 

Invalid request; function code out of range. 

In the XM monitor, the user buffer address is not in valid 
user virtual address space. 



Example: 

Refer to the example for the .MTATCH request. 

2.54 .MTOUT (Special Feature) 

The .MTOUT request transfers characters to the terminal output buffer. 
This request is the multiterminal form of the .TTYOUT request. The 
.MTOUT request moves one or more characters from the user's buffer to the 
output ring buffer of the terminal. The terminal must be attached. An 
updated user buffer address is returned in RO if the request is successful. 
When there is no room in the output ring buffer, the carry bit is set and an 
error code of is returned in byte 52 if bit 6 is set in M.TSTS. Otherwise, 
the job is suspended until room becomes available. 

If a multiple-character request was made and there is not enough room in 
the output ring buffer to transfer the requested number of characters, the 
request can either wait for enough room to become available, or it can 
return with a partial transfer. If bit 6 in M.TSTS is clear, the request waits 
until it can complete the full transfer. If bit 6 is set, the request returns 
with a partial transfer. In the latter case, RO contains the updated buffer 
address (pointing past the last character transferred), the C bit is set, and 
the error code is 0. 

The meaning of bit 6 in the terminal configuration word (M TSTS) for the 
.MTOUT request is as follows: 

Bit 6 Meaning 

Normal mode for output; wait for room, in buffer 

1 Carry bit set: no room in output ring buffer 
Macro Call: .MTOUT area,addr,unit[,chrcnt] 

where: 

area is the address of a three-word EMT argument block 
addr is the address of the caller's input buffer 
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unit 



is the unit number of the terminal 



chrcnt is a character count indicating the number of characters to 
transfer. The valid range is from 1 to 255(decimal) 

Request Format: 

RO —> area: 



37 3 


addr 


chrcnt unit 



Errors: 

Code Explanation 

No room in output buffer. 

1 Invalid unit number, unit not attached. 

2 Nonexistent logical unit number. 

3 Invalid request; function code out of range. 

5 In the XM monitor, the user buffer address is not in valid 

user virtual address space. 

Example: 

Refer to the example for the .MTATCH request. 

2.55 MTPRUJ (Special Feature) 

This .MTPRNT request allows one or more lines to be printed at the speci- 
fied terminal in a multiterminal environment. It is equivalent to the 
.PRINT request (see .MTSET request for more details). The string to be 
printed must be terminated with a null byte or a 200 byte, similar to the 
string used with the .PRINT request as follows: 



or 



.ASCIZ /string/ 
.ASCII /string/<200> 



The null byte causes a carriage return/line feed combination to be printed 
after the string. The 200 byte suppresses the carriage return/line feed com- 
bination and leaves the carriage positioned after the last character of the 
string. The request does not return until the transfer is complete. 






where: 



A/TTiTSPXTT 



area is the address of a three-word EMT argument block 

addr is the starting address of the character string to be printed 

unit is the unit number associated with the terminal 
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2.56 



Request Format: 
RO -^ area: 

Errors: 



37 7 


addr 


— unit 



Code Explanation 

1 Invalid unit number, unit not attached. 

2 Nonexistent logical unit number. 

3 Invalid request; function code out of range. 

5 In the XM monitor, the character string address is not in 

valid user virtual address space. 

Example: 

Refer to the example for the .MTATCH request. 

ITPS 

See .MFPS/.MTPS (Section 2.48). 



2.57 .MTRCTO (Special Feature) 

The .MTRCTO request resets the CTRL/0 switch of the specified terminal 
and enables terminal output in a multiterminal environment. It is equiva- 
lent to the .RCTRLO request. 

Macro Call: .MTRCTO area,unit 

where: 

area is the address of a three-word EMT argument block 
unit is the unit number associated with the terminal 

Request Format: 
RO -^ area: 



37 4 


unused 


— unit 



Errors: 

Code 

1 

2 

3 

Example: 

Refer to the example for the .MTATCH request 



Explanation 

Invalid unit number, unit not attached. 

Nonexistent logical unit number. 

Invalid request; function code out of range. 
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2.58 .MTSET (Special Feature) 

This multiterminal request sets terminal and line characteristics. It also 
determines the input/output mode of the terminal service requests for the 
specified terminal. 

Macro Call: .MTSET area,addr,unit 

where: 

area is the address of a three-word EMT argument block 

addr is the address of a four-word status block containing the line 
and terminal status being requested 

unit is the logical unit number associated with the line and termi- 
nal 

Request Format: 

RO -> area: 



37 1 


addr 


— unit 



When the program returns from the request, the status block contains the 
following information: 

Byte Offset Contents 

Terminal configuration word 1 (The bit definitions 

are the same as those for the .MTGET request.) 

2 Terminal configuration word 2 (The bit definitions 

are the same as those for the .MTGET request.) 

4 Character requiring fillers 

5 Number of fillers 

6 Carriage width (byte) 

NOTE 

The .MTSET request sets all of the parameters listed above. 
The recommended procedure for using .MTSET is: (1) precede 
it by an .MTGET request; (2) use BIS and BIC instructions to 
set or clear bit fields (modify only the bits or bytes that you 
intend to change); (3) issue the .MTSET request to replace 
the previous terminal status with the updated status. 

Note that if an error occurs, and the error code is not 1, the status block will 
not have been modified. 

Errors: 

Code Explanation 

1 Invalid unit number, lun not attached. 

2 Nonexistent logical unit number. 



2-86 Programmed Request Description and Examples 



3 Invalid request, function code out of range. 

5 In the XM monitor, the status block address is not in valid 

user virtual address space. 

Example: 

Refer to the example for the .MTATCH request. 

2.59 .MTSTAT (Special Feature) 

The .MTSTAT request returns multiterminal system status information. 

Macro Call: .MTSTAT area,addr 

where: 

area is the address of a three-word EMT block 

addr is the address of an eight-word status block where multiter- 
minal status information is returned. The status block con- 
tains the following information: 

Byte Offset Contents 

Offset from the base of the resident monitor 

to the first terminal control block (TCB) 

2 Offset from the base of the resident monitor 

to the terminal control block of the console 
terminal for the program 

4 The value (0-16 decimal) of the highest logi- 

cal unit number (LUN) built into the system 

6 The size of the terminal control block in 

bytes 

10-17 Reserved 

Request Format: 

RO -^ area: 



37 



10 



addr 



Errors: 

Code Explanation 

3 Invalid request; function code out of range 

5 In XM, the status block address is not in valid user address 

space. 

Example: 

Refer to the example for the .MTATCH request. 
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2.60 .MWAIT (FB and KM Only) 

This request is similar to the .WAIT request. .MWAIT, however, suspends 
execution of the job issuing the request until all messages sent to the other 
job or requested from the other job have been received. It should be used 
with the .RCVD or .SDAT modes of message handling, where no action is 
taken when a message is completed. 

Macro call: .MWAIT 

Request Format: 

RO = 
Errors: 

None 
Example: 



11 



• MWAIT - This is an example in the use of the .MWflIT re'iuest. 
The example is actually two programs) a Background Job 
which sends messases t and a Foresfround Job i which reoeiues them. 
NOTE! Each proSram should be assembled and linked separately. 



.TITLE 
i + 
i Foresround ProSram 



MWfllTF.MflC 



MWAITF! 



FEXIT: 

AREA: 

MBUFF! 

FGJOB: 
FMSG: 



.MCALL 
.RCVD 



PRINT 



.MWAIT 

TST 

BED 

.PRINT 

.PRINT 

BR 

.EXIT 

.BLKM 

.BLKW 

.WORD 

.ASCIZ 

.ASCIZ 

.END 

.TITLE 



.RCVD.. MWAIT.. PR I NT I. EXIT 



«AREA.»MBUFF.«aO. 



SFGJOB 



.Request a message up to 80 char. 
SNo error possible - always a BG 



iDo seme other processing 
ilike announcing FG active... 



.Wait for message to arriue... 
MBUFF+2 iNull messaSe? 

FEXIT .Yes. ..exit the proSram 

«FMSG .Announce we Sot the message... 

8MBUFF+2 .and echo it back 

MWAITF .Loop to 3et another one 

SExit program 
5 lEMT Argument Block 

ai. .Buffer - Mss lensth + 1 

iMake sure 80 char messaSe ends ASCIZ 

/Hi - FG aliue and well and waitins for a message!/ 
/Hey BG - Got your message it reads:/ 
MWAITF 

MWAITB.MAC 



i + 

i BackSround ProSram - Send a 'null' message to stop both programs 



MWAITB: 



.MCALL 

CLR 

.GTLIN 

.SDAT 

BCS 

.MWAIT 



.SDAT.. MWAIT.. GTLIN.. EX IT.. PR I NT 



BUFF 

•BUFF.aPRDMT 

• AREA .»BUFF .»aO. 

1$ 



iClear 1st word 

!Get somethins to send to FG from TTY 

iSend input as message to FG 

iBranch on error - No FG 

iWait for message to be sent 
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TST 


BUFF 






iSent a nul 1 messaSe? 




BNE 


MWAITB 






iNo...loop to send another messase 




.EXIT 








iYes ...exit pros ram 


1$: 


PRINT 
.EXIT 


»NOFG 






;No FG ! 

iExi t pro Srain 


AREA: 


.BLKW 


5 






iEMT Argument Block 


BUFF: 


.BLKN 


ao. 






iUp to SO char messaSe 


PROMT: 


.ASCII 


/Ente r 


message 


to be 


sent to FG Job/< 15>< 12>/>/<200> 


NDFG: 


.ASCIZ 
.END 


/?No FG 
MWAITB 


?/ 







2.61 .PEEK/.POKE 



The .PEEK programmed request returns in RO the contents of a memory 
location; .POKE changes the contents of a memory location. The .POKE 
request also returns the old contents of the memory location in RO to sim- 
plify the saving and restoring of a location. .PEEK and .POKE must be 
used in an XM environment to change memory locations that are not de- 
fined as monitor fixed offsets, and should be used with all RT-11 monitors 
for compatibility. 

Although .PEEK and .POKE may seem very similar to .GVAL and .PVAL, 
respectively, they are different in the way they refer to locations. .GVAL 
and .PVAL access only monitor fixed offsets. All offsets used by .GVAL and 
.PVAL are calculated relative to the base of the resident monitor. Ad- 
dresses used by .PEEK and .POKE, on the other hand, are simply memory 
addresses. Although .PEEK and .POKE can be used to access monitor fixed 
offsets, this requires that you find the base address of RMON, add the offset 
value, and use the resulting address as an argument to .PEEK or .POKE. 

Macro Calls: .PEEK area,address 



.POKE area, address,value 



where: 



area is the address of a two- or three-word EMT argument block 

address is the address of the location to examine or change 
value is the new contents to place in the location 

Request Format for .PEEK: 
RO - 



RO 



area: 


34 


1 




address 


lat for 


.POKE: 


area: 


34 


3 




address 




value 



Errors: 



None. 
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Example: 



lExaitiplB of I PEEK and .POKE programmed requests. 
iThis example illustrates a uav of readins and settins 
ithe default file size used by the .ENTER re-iuest. 
JNormallvi this would be done usins the .G^ftL and . PVflL proSrammed 
ireiuests. (Refer to the example siuen for the . PVAL request.) This 
iexample oomputes the address of the word in RMDN oontaininS the 
idefault file size used by the .ENTER request and uses .POKE 
iboth to chanSe the default file size to 100. blocks and to return 
ithe old default file size in RO. 



START: 



.MCflLL 


.PEEK 1 


.POKE, .Exn 


RMON = 


54 




MfiXBLK= 


314 




.PEEK 


KEMTBLK 


,oRMON 


ftDD 


»MAXBLK 


, RO 


MOO 


RO, 


Rl 


.POKE 


ttEMTBLK 


, Rl , ONEWSIZ 


MOM 


RO, 


OLDSIZ 


.EXIT 







EMTBLK: 


.BLKW 


3 


NEWSIZ: 


.WORD 


100.. 


OLDSIH: 


.WORD 






iPioK UP base of RMON from loc, 54 

iAdd fixed offset of default file size, 

iSet a new default file size, return old 

idefault file size in RO and saue the old size 

iWe'll Just exit now, but presumably 

iin a real program we'd do more 

iprooessinS, perhaps oreatinS files 

iwith the new default size we Just set, then 

ibefore exiting we'd restore the old 

idefault size. 

iEMT area 

iEMT area 

iThe old default size is saued here. 



.END 



START 



2.62 .POKE 

Refer to .PEEK/.POKE (Section 2.61). 

2.63 .PRINT 

The .PRINT request causes output to be printed at the console terminal. 
The string to be printed can be terminated with either a null (0) byte or a 
200 byte. If the null (ASCIZ) format is used, the output is automatically 
followed by a carriage return/line feed combination. If a 200 byte termi- 
nates the string, no carriage return/line feed combination is generated. 

Control returns to the user program after all characters have been placed 
in the output buffer. 

When a foreground job is running and the job that is producing output 
changes, a B> or F> appears. Any text following the message has been 
printed by the job indicated (foreground or background) until another B> 
or F> is printed. 

When a system job prints a message to the terminal, the message is pre- 
ceded by logical -job -name. 

If the foreground job issues a message using .PRINT, the message is printed 
immediately, no matter what the state of the background job. Thus, for 
urgent messages, the .PRINT request should be used (rather than 
.TTYOUT or .TTOUTR). The .PRINT request forces a console switch and 
guarantees printing of the input line. If a background job is doing a prompt 
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and has printed an asterisk but no carriage return/line feed combination, 
the console belongs to the background and .TTYOUTs from the foreground 
are not printed until a carriage return is typed to the background. A fore- 
ground job can force its message through by doing a .PRINT instead of the 
.TTYOUT. 

Macro Call: .PRINT addr 

where: 

addr is the address of the string to be printed 
Errors: 

None. 
Example: 

.TITLE PRINT. MAC 

> + 

i .PRINT - This is an example in the use of the .PRINT request. 
i The example merely accepts input from the console terminal and 
i echoes it back. 



.MCALL 



.GTLIN ..PRINTi.EXIT 



START! 


.GTLIN 


«BUFF 1 


iSPROMT 


iGet a line of input from Keyboard 




TSTB 


BUFF 






iNoth ins entered? 




BEO 


1$ 






iBranoh if nothinS entered 




.PRINT 


ttBUFF 






iEoho the input bacK 




CLRB 


BUFF 






iCIear first char of buffer 




BR 


START 






iGo bacK for more 


1$! 


.EXIT 








iExit prosram on null input 


BUFF: 


.BLKW 


41. 






i80 character buffer (ftSCIZ for .PRINT) 


PROMT: 


.ASCII 
.END 


/Ente I 
START 


■ some 


th 


inS/<15><12>/>/<Z00> 



2.64 .PROTECT/.UNPROTECT (FB and XM Only) 

.PROTECT 

The .PROTECT request allows a job to obtain exclusive control of a vector 
(two words) in the region to 474. If the request is successful, it indicates 
that the locations are not currently in use by another job or by the monitor. 
The job then can place an interrupt address and priority into the protected 
locations and begin using the associated device. 

Macro Call: .PROTECT area, addr 

where: 

area is the address of a two-word EMT argument block 
addr is the address of the word pair to be protected 

NOTE 

The argument addr must be a multiple of four, and must be 
less than or equal to 474(octal). The two words at addr and 
addr + 2 are protected. 
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Request Format: 
RO —> area: 



Errors: 

Code 

1 

Example: 



31 



addr 



Explanation 

Protect failure; locations already in use. 

Address (addr) is greater than 474 or is not a multiple of 4. 



.TITLE PROTEC.MAC 



• PROTECT / .UNPROTECT - This is an example in the use of the .PROTECT 
and .UNPROTECT requests. The example illustrates hou to proteot the 
uectors of a deuioe while an inline interrupt seruice routine does 
a data transfer (in this case the deuioe is a DLll Serial Line Interface), 
When the proSram is finished) the vectors are unprotected for possible 
use by another Job. 



START: 



FINl! 
BUSY: 



AREA: 
LIST: 



BUFFR: 



NOyEC: 



.MCALL 



.DEVICE 



.PROTECT 
BCS 



JSR 



.MORD 
. NORD 



.UNPROTECT 

.EXIT 

.PRINT 

.EXIT 

.BLKN 

.WORD 

.WORD 

.WORD 

.REPT 
.ASCIZ 
.ENDR 
.ASCIZ 

.END 



. DEVICE , .EXIT . . PROTECT . .UNPROTECT .. PRINT 
»AREA.»LIST 



"AREA .«300 
BUSY 



R5.DLU 



128. 
BUFFR 



iSetup to disable DLll interrupts on 

i.EXIT or -C-C 

iProtect the DLll uectors 

iBranoh if already protected 

iSet UP data to transmit ouer DLll 

iUse DLll xfer routine (see .INTEN 

) exampl e ) 

iArSuments . . . Wo rd count 

iData buf f e r addr 

{Continue processing... 

i . . . euent ual 1 y to exit proSram 

iPrint error message... 

! t hen exit 

lEMT ArSument blooK 

iCSR of DLll 

iStuf f it with '0 ' 

iList terminator 

iData to send ouer DLll 

is lines of 32 characters... 



• AREA >»300 

SNOVEC 

3 

17S500 





8. 

/Hello DLll... Are You There ??/ 

/?Vector already protected?/ iError messaSe text 

START 



.UNPROTECT 

The .UNPROTECT request is the complement of the .PROTECT request. It 
cancels any protected vectors in the to 476 area. An attempt to unprotect 
a vector that a job has not protected is ignored. 

Macro Call: .UNPROTECT area.addr 



where: 



area is the address of a two-word EMT argument block 
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addr is the address of the protected vector pair that is going to be 
canceled. The argument addr must be a multiple of four, and 
must be less than or equal to 474(octal) 

Request Format: 



RO — > area: 



31 



addr 



Errors: 

Code Explanation 



1 



Address {addr) is greater than 474(octal) or is not a multiple 
of four. 



Example: 

Refer to the example for the .PROTECT request. 

2.65 PURGE 

The .PURGE request deactivates a channel without performing a 
.HRESET, .SRESET, .SAVESTATUS, or .CLOSE request. .PURGE frees a 
channel without taking any other action. If a tentative file has been en- 
tered on the channel, the file is discarded. An attempt to purge an inactive 
channel is ignored. 

NOTE 

Do not purge channel 17(octal) if your program is overlaid 
because overlays are read on that channel. 

Macro Call: .PURGE chan 
where: 

chan is the number of the channel to be freed 
Request Format: 



RO = 1 3 Ichan 
Errors: 

None. 
Example: 

.TITLE PURGE. MAC 



i .PURGE - This is an example in the use of the PURGE re-iuest, 
i This example merSes 2-B files into 1 file. maKinS use of .SAVESTATUS 
! and .REOPEN to read all input files on one channel. The .PURGE resuest 
i is used to free the input channel after each transfer. 



• MCALL .CSIGEN .. SAVESTATUS . .REOPEN . .CLOSE , .EXIT 
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START: 



1$: 



2$: 

at: 

5i: 



6$: 



7$: 

B»: 
3$: 

AREA: 

BLK: 

WBLK: 

SftyBLK: 

DEFEXT: 

NQINP: 

NERR: 

RERR: 

DONE; 

BUFFR: 
DSPACE 



.MCALL 
ERRBYT 

.CSIGEN 
MOV 

Moy 
Moy 

.SAMEST 

BCS 

ADD 

INC 

CMP 

BGE 

MOV 

BEO 

.REOPEN 

CLR 

.READW 

BCC 

TSTB 

BNE 

.PURGE 

ADD 

TST 

BNE 

.CLOSE 

.PRINT 

.EXIT 

.WRITW 

INC 

INC 

BCC 

MOV 

BR 

MOVE 

BR 

MOV 

.PRINT 

.EXIT 

.BLKW 

.WORD 

.WORD 

.BLKW 

.WORD 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.EVEN 

.BLKW 



.READW , .WRITW .. PRINT . . PURGE 

= 52 iError byte loo in SYSCOM 



oDSPACE.itDEFEXT 

«3,Rfl 

•AREAiRS 

sSAVBLK .R5 

R3,R^ (R5 

2* 

»12.R5 

Ra 

«8. .Ra 

1* 

SSAVBLK .R5 

7$ 

R3.»3.R5 

BLK 

R3.«3. "BUFFR i»25B. 

8* 

§«ERRBYT 

8* 

«3 

sl2 .R5 

eR5 

• DONE 

R3.»0.«BUFFR.»25G, 

WBLK 

BLK 

5* 

•WERR.RO 

9$ 

•NOINPiRO 

9t 

SRERR.RO 



5 





30. 

lO lO lO 

/?No input files?/ 

/?Write Error?/ 

/?Read Erro r?/ 

/I-O Transf e r Comp 



iGet file speoiopen filesiload handlers 

iRa = Ist input channel 

iR3 => EMT ArSument blocK 

!R5 => Channel savestatus blooKs 

iSaue channel status 

iBranch if channel neuer opened 

iAdJust R5 to point to next status blooK 

iBump Rii to = next input channel 

iDone all input channels? 

iBranch if not 

iR5 => to Ist saued channel status 

iBranch if no input files 

iRe-open input channel on Ch 3 

iStart readinS uith blocK 
iBLK iRead a block 

iBranch if no error 

iCheck if error = EOF 

iBranch if not EOF 

iClear input channel for re-use 

iPoint R5 to next saued ch status 

iAny more input channels? 

iBranch if yes 

iWe're done. ..close output channel 

iAnnounce werSe complete 

iExi t pros ram 
tWBLK iWrite block Just read 

iBump to next output block 

isame for input blk (doesn't affect C bit) 

iBranch if no error on urite 

iWrite error - RO => message 

ime r Se . . . 

iRO => No input files messase 

ime rSe . . . 

iRO => Read error message 

iRepo rt error 

ithen exit proSram 

iEMT A rSument block 

iCurrent read block 

iCurrent write block 

iSaued channel status area 

iNo default extensions for CSIGEN 

iError messages 



leted/ 



Z5B. 



iI/0 buffer 

iHandlers start here.. 



.END 



START 



2.66 PVAL 

See .GVAL/.PVAL (Section 2.41). 



2.67 .QELDF (Device Handler Only) 

The .QELDF macro symbolically defines queue element offsets for the spec- 
ified set of system generation special features. The queue element offsets 
generated by this macro are as follows: 



Q.LINK = 
Q.CSW = 2. 
Q.BLKN = 4. 



(Link to next queue element) 
(Pointer to channel status word) 
(Physical block number) 
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Q.FUNC = 6. (Special function code) 

Q.JNUM = 7. (Job number) 

Q.UNIT = 7. (Device unit number) 

Q.BUFF = ''O10 (User virtual memory buffer address) 

Q. WCNT = "012 (Word count) 

Q.C0MP = '014 (Completion routine code) 

Since the handler usually deals with queue element offsets relative to 
Q.BLKN, the .QELDF macro also defines the following symbolic offsets: 

Q$LINK--4 
Q$CSW=-2 
Q$BLKN = 
Q$FUNC = 2 
Q$JNUM = 3 
Q$UNIT = 3 
Q$BUFF=4 
Q$WCNT=6 



) Q$COMP = "O10 



For SJ and FB systems: 

Q.ELGH = "016 (End of queue element; used to find length) 

For XM systems: 

Q.PAR = "016 (PARI relocation bias) 

Q$PAR = "012 

Q.ELGH = "024 (End of queue element; used to find length) 

Example: 

Refer to the example following the description of .DRAST. 



2.68 .QSET 



The .QSET request allows additional entries to be made to the RT-11 I/O 
queue. A general rule to follow is that each program should contain one 
more queue element than the total number of I/O requests that will be 
active simultaneously on different channels. Timing and message requests 
such as .MRKT, .TWAIT, .SDAT/C, and .RCVD/C also require queue ele- 
ments and must be considered when allocating queue elements for a pro- 
gram. Note that if synchronous I/O is done (such as .READW/.WRITW) and 
no timing requests are done, no additional queue elements need be alio- 






Each time .QSET is called, a specified contiguous area of memory is divided 
into seven- word segments (10- word [decimal] segments for the XM monitor) 
and is added to the queue for that job. .QSET can be called as many times 
as required. The queue set up by multiple .QSET requests is a linked list. 
Thus, .QSET need not be called with strictly contiguous arguments. The 
space used for the new elements is allocated from your program space. Care 
must be taken so that the program in no way alters the elements once they 
are set up. The .SRESET and .HRESET requests discard all user-defined 
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queue elements; therefore any previous .QSET requests must be reissued. 
However, you must not specify the same space in two separate .QSET re- 
quests if there has been no intervening .SRESET or .HRESET request. 

Care should also be taken to allocate sufficient memory for the number of 
queue elements requested. The elements in the queue are altered asynchro- 
nously by the monitor; if enough space is not allocated, destructive refer- 
ences occur in an unexpected area of memory. The monitor returns the 
address of the first unused word beyond the queue elements. Other restric- 
tions on the placement of queue elements are that the USR must not swap 
over them and they must not be in an overlay region. For jobs that run 
under the XM monitor, queue elements must be allocated in the lower 28K 
words of memory, since they must be accessible in kernel mapping. In 
addition, the elements must not be in the virtual address space mapped by 
kernel PARI, specifically the area from 20000 to 37776(octal). 

NOTE 

Programs that are to run in XM as well as SJ or FB environ- 
ments should allocate lO(decimal) words for each queue ele- 
ment. Alternatively, a program can specify the start of a 
large area and use the returned value in RO as the top of the 
queue element. 

The following programmed requests require queue elements: 



.TWAIT 


.READW .WRITE 


.SDAT 


.MRKT 


.RCVD .WRITC 


.SDATC 


.READ 


.RCVDC .WRITW 


.SDATW 


.READC 


.RCVDW 




Macro Call: . 


QSET addr,len 




where: 







addr is the address at which the new elements are to start 

len is the number of entries to be added. In the SJ and FB moni- 
tor, each queue entry is seven words long; hence the space set 
aside for the queue should be len*l words. In the XM monitor, 
10 (decimal) words per queue element are required 

On completion, RO contains the address of the first word beyond the allo- 
cated queue elements. 



T7I „. 

±H11 UIO. 



In an extended memory environment, an attempt to violate the PARI 
restriction results in a ?MON-F-addr error, which can be intercepted 
with a .SERR programmed request. 

Example: 

■TITLE OBET.MflC 
i + 

i iCJBET - This is an example in the use of the .OSET request. 
j The exatiiple illustrates a user itiipl etiien t ed "Timed Read" to cancel an 
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input request after a specified time interual. 

.MCflLL ,MRKT,.TTINR .. EXIT .. PRINT .. TTYOUT .. CMKT ., TWAIT ., OSET 



START: 
1$: 



Z$! 



TREflD$: 



1*: 



TTIN: 



TBYT! 



2$: 
3$: 



TOUT: 

XOUE: 

AREA: 

TAREA: 

TIME: 

WAIT: 

LINE: 

BUFFR: 

PROMT: 

TIMOUT: 



LF = 12 

jsw = aa 

TCBIT$ = 100 
TTSPC* = 10000 



.OSET 

MOM 

MOO 

CALL 

BCS 

•PRINT 

BR 

.PRINT 

.EXIT 

i* TREAD$ 
1* Input : 

!# 

;* Output : 
i* 

TST 

BEO 

.PRINT 

CLR 

.MRKT 

BIS 

CLRB 

.TWAIT 

.TTINR 

BIT 

.WORD 

BNE 

BCB 

MOMB 

.CMKT 

BIS 

.TTINR 

MOMB 

BCC 

CLRB 

BIC 

ROR 

RETURN 

INC 

RETURN 

.BLKW 

.WORD 

.BLKW 

.WORD 

.WORD 

.ASCII 

.BLKB 

.ASCIZ 

.ASCIZ 

.END 



»XC)UE,«1 
"PROMT. RO 
"BUFFR. Rl 
TREAD$ 
2$ 

"LINE 
1$ 
"TIMOUT 



iLine Feed 

iJob Status Word location 
iReturn C-bit bit in JSW 
iTTY Special Mode bit in JSW 

iNeed an extra 0-Elem for this 

iMainline - RO => Prompt 

iRl => Input buf f e r 

iDo a "timed read" 

iC~bit set = Timed out 

i "Process" data... 

;Go back for more 

iRead timed out - could process 

ipartial data but we'll Just exit 



"Timed Read" Subroutine 
RO => Prompt Strins / RO = if no prompt 
Rl => Input Buffer 

Buffer contains input chars.. if any. terminated 
by a null char. C-Bit set if timed out 



RO 
1* 

TBYT 

"TAREA ."TIME ."TOUT ."1 

»TCBIT$ i@«JSW 

SRI 

"AREA 

sl .(PC) + 



2* 

TTIN 

RO ,(R1) + 

"TAREA. "0 

"TTSPC* ,@"JSW 

RO.CRl )+ 

3$ 

-(Rl ) 

"TCBIT$!TTSPC* .e"JSW 

TBYT 

TBYT 

10. 
OiWAIT 

a 

O.GOO. 

0.1 

/Not in stock - Part " 

81. 

/Enter Part » >/<200> 

/Timed read expired!/ 

START 



See if uie have to prompt 

B ranch if no . , . 

Output p rompt 

Clear time-out flaS 

Issue a .MRKT for 10 see 

Set C-Bit bit in JSW (for F/B) 

Start with "empty" buffer 

Wait so ue don't look out BG 

Look for a character 

Timed out? 

Time-out f las 

Branch if yes 

Branch if input not complete 

Xfer 1st character 

Cancel .MRKT 

Turn on TT : Special mode 

Flush TT: rins buffer 

puttins characters in user buffer 

If more char. So Set 'em 

Terminate input with null byte 

Clear bits in JSW 

Set carry if timed out 

Return to caller 

SLeaue completion code 
iEx t ra 0-Element 
iEMT Arsument block for .TWAIT 
!EMT Arsument block for .MRKT 
iTime-out interval (10 sec) 
il/BO sec wait between .TTINRs 
' jDummy response 
iUse r input buffer 
iP rompt 
!Too bad messase 



2.69 .RCTRLO 



The .RCTRLO request makes sure that the console terminal is able to print 
by resetting the CTRL/0 switch for the terminal. A CTRL/0 typed while 
output is directed to the console terminal inhibits the output from printing 
until either another CTRL/0 is struck or the program resets the CTRL/0 
switch. Therefore, a program with a message that must appear at the con- 
sole should reset the CTRL/0 switch. 



Programmed Request Description and Examples 2-97 



A program should also issue a .RCTRLO request whenever it changes the 
contents of the job status word (JSW). Issuing a .RCTRLO request updates 
the monitor's internal status information to reflect the current contents of 
the JSW. 

Macro Call: .RCTRLO 

Errors: 

None. 

Example: 



.TITLE RCTRLO, MAC 
y 

.RCTRLO - This is an example in the use of the .RCTRLO request. 
In this exaiiiplei the user prosram first calls the CSI in Seneral rnodei 
then processes the oommand. When finished i it returns to the CSI for 
another comwand line. To niaKe sure that the prompting '*' typed by 
the CSI is not inhibited by a CTRL-0 in effect from the last operationi 
terminal output is assured uia the .RCTRLO re-iuest prior to the 
CSI call. 



START: 



.MCALL 



.RCTRLO 
.CSIGEN 



.RCTRLO ..CSIGEN. .EXIT 



«DSPACE.»DEXT.aO 



iMaKe sure TT: output is enabled 

ilssue a .CSIGEN re-iuest to Set 

ioommand 

!(CSI will prompt with '♦') 

iProcBss the command... 





JMP 


START 


DEXT: 


.WORD 


lO .0 .0 


DSPACE: 


- , 





iGet another command... 

iNo default extensions 

iSpace for handlers starts here 



.END 



START 



2.70 .RCVD/.RCVDC/.RCVDW (FB and XM Only) 

The .RCVD (receive data) request allows a job to read messages or data 
sent by another job in an FB environment. 

There are three forms of the .RCVD request, and they are used with the 
.SDAT (send data) request. The send data-receive data request combination 
provides a general data/message transfer system for communication be- 
tween a foreground and a background job. .RCVD requests can be thought 
of as .READ requests where data transfer is not from a peripheral device 

1 J. £. J.l._ _i.l -^U -— J-l-~ „J-„ — A JJ4j-:„ 1 « «1„ — J-„ ,.,1,«,,1J U„ 

UUL iruiu Lilts ui/iici juu 111 i/iic is^BLcui. nuui Liuiiai nucuc ciciiiciii.o iaiiuu-iu. uc 

allocated for buffered I/O operations in .RCVD and .RCVDC requests (see 
the .QSET request). Under an FB monitor with the system job feature, 
.RCVD/C/W requests and .SDAT/C/W requests remain valid for sending 
messages between background and foreground jobs in addition to the gen- 
eral read and write capability available to all jobs. 

Be particularly careful if you use both synchronous (.RCVDW and 
.SDATW) and asynchronous (.RCVDC and .SDATC) requests in the same 
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program. If you issue a mainline .SDATW while there is a pending 
.RCVDC, the .SDATW will wait until the .RCVDC is satisfied. If the com- 
pletion routine for the .RCVDC issues another .RCVDC, the mainline 
.SDATW will never complete. In general, you should avoid the use of both 
synchronous and asynchronous message requests in the same program. 

.RCVD 

This request is used to receive data and continue execution. The request is 

posted and the issuing job continues execution. When the job needs to have 

the transmitted message, an .MWAIT should be executed. This causes the 

job to be suspended until all .SDATx and .RCVDx requests for the job are 

complete. 

Macro Call: .RCVD area,buf,wcnt 

where: 

area is the address of a five-word EMT argument block 

buf is the address of the buffer into which the message 
length/message data is to be placed 

went is the number of words to be transferred 

Request Format: 

RO —> area: 



26 



reserved 



buf 



went 



Upon completion of the .RCVD, the first word of the message buffer con- 
tains the number of words transmitted. Thus, the space allocated for the 
message should always be at least one word larger than the actual message 
size expected. If the sending job attempts to send more words than the 
receiver specified in the went argument of the .RCVD request, the first 
word of the buffer will contain the number of words that the sender speci- 
fied, but only went words will be actually transferred. The rest of the 
sender's message will be ignored. 

The word count is a variable number, and as such, the .SDAT/.RCVD com- 
bination can be used to transmit a few words or entire buffers. The .RCVD 
operation is only complete when a .SDAT is issued from the other job. 

Programs using .RCVD/. SDAT must be carefully designed to either always 
transmit/receive data in a fixed format or to have the capability of handling 
variable formats. Messages are all processed in first-in first-out order. 
Thus, the receiver must be certain it is receiving the message it actually 
wants. Message handling in the FB monitor does not check for a word count 
of zero before queuing a send or receive data request. Since RT-11 distin- 
guishes a send from a receive by complementing the word count, a .SDAT of 
zero words is treated as a .RCVD of zero words. Avoid a word count of zero 
at all times when using a .RCVD request. 
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Errors: 



Code Explanation 

No other job exists in the system. (A job exists as long as it is 
loaded, whether or not it is active.) 

Example: 

Refer to the example for the .SDAT request. 

.RCVDC 

The .RCVDC request receives data and enters a completion routine when 
the message is received. The .RCVDC request is posted and the issuing job 
continues to execute. When the other job sends a message, the completion 
routine specified is entered. 

Macro Call: .RCVDC area,buf,wcnt,crtn 

where: 

is the address of a five-word EMT argument block 



area 
buf 

went 
crtn 



is the address of the buffer into which the message 
length/message data is to be placed 

is the number of words to be transmitted 

is the address of a completion routine to be entered 



As in the .RCVD request, word of the buffer contains the number of words 
transmitted when the transfer is complete. 

Request Format: 

RO —> area: 



26 







reserved 



buf 



went 



crtn 



Errors: 

Code 



Example: 



Explanation 

No other job exists in the system. (A job exists as long as it is 
loaded, whether or not it is active.) 



.TITLE RCVDC. MAC 



.RCVDC - This is an example of the .RCVDC request. The example 
is a simulation of a mainline Foresround program which is currently 
suspended waitins for a messase from the BaoKSroundt but which needs 
to close a file (perhaps opened by a .ENTER ?) before aborting from 
CTRL-C action, fi completion routine periodically inspects the CTRL-C 
status word and resumes the mainline if double CTRL-C is entered. 
NOTE: This example MUST be run as a FG Job under an FB monitor. 
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.MCftLL 


.SCCft ..RCyOCi.EXIT ..PRINT 




.MCALL 


.QSET i.SPND i.RSUM 


START: 


■ OSET 


ttOELEM i«l 




.SCCA 


«MflREA.»SCCA 


1$: 


CftLL 


CWATCH 




.Rcyoc 


itMAREA ,«MBUFF ,»«0. i»MESG 




.PRINT 


SSLEEP 




.SPND 






TST 


SCCA 




BNE 
5 


CLOSE 




i <proce55 messaSe here> 
■ 




BR 


1$ 


CWftTCH: 


TST 


SCCA 




BEO 


MARK 


MESG: 


RETURN 


.RSUM 


MARK: 


.MRKT 
RETURN 


»CAREA,aTIME,«CWATCH,«l 



CLOSE: 



OELEM: 

MBUFF: 

MAREA: 

CAREA: 

TIME: 

SCCA: 

ABORT; 
SLEEP: 



.PRINT «ABORT 

i <0utput file(5) closed here> 



.EXIT 

.BLKW 
.BLKW 
.BLKW 
.BLKW 
.WORD 
.WORD 

.ASCIZ 
.ASCI2 

.END 



7 

a\ . 

5 

a 

,B00. 




iAllocate another O-Eleinent 

1 1 n h i b i t ' C ' C action by monitor 

iStart "watchdog" completion rtne 

iLooK for a message 

!No errors - there's always BG 

iOther processing hers... 

i 

iAnnounoe we're soinS to suspend 

iSu spend to wait for messaSe 

iWe'ue been . RSUMe d . . . 'C-C hit?? 

i Branch if yes 

iotheruise assume messaSe came in. 



tLo p . t t 

iCheoK if "C'C entered... 

5 Branch if no 

i Y e s . . . w a K e up the mainline 

ithen leaue completion code 

iSchedule to run asain in 10 sec. 

ithen leaue completion code 

iAnnounoe we're abortins 
iproceed with "orderly" abort 



iExit the pros ram 

iExtra 0-Element 

iMessaSe buffer 

iEMT Argument blooKs 

i 

iTime out in 10 seconds 

i'-CC Status word 



/?! Abort AcKnowledSed . . .ClosinS Output File(s) ! ?/ 
/! Mainline Suspendins !/ 



START 



.RCVDW 

.RCVDW is used to receive data and wait. A message request is posted and 
the job issuing the request is suspended until all pending .SDATx and 
.RCVDx requests for the job are complete. When the issuing job runs again, 
the message has been received, and word of the buffer indicates the num- 
ber of words transmitted. 



Macro Call: 

where: 

area 
buf 

went 



.RCVDW area,buf,wcnt 

is the address of a five-word EMT argument block 

is the address of the buffer into which the message 
length/message data is to be placed 

is the number of words to be transmitted 



Request Format: 
RO -^ area: 



26 



reserved 



buf 



went 
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Errors: 

Code Explanation 

No other job exists in the system. (A job exists as long as it is 
loaded, whether or not it is active.) 

Example: 

Refer to the example for the .SDATW request. 



2.71 .RDBBK (KM Only) 



The .RDBBK macro defines symbols for the region definition block and 
reserves space for it. The .RDBBK automatically invokes .RDBDF. 

Macro Call: .RDBBK rgsiz 

where: 

rgsiz is the size of the dynamic region needed (expressed in 32- 
word units) 

Example: 

See Chapter 4 of the RT-11 Software Support Manual for an example 
that uses the .RDBBK macro and a detailed description of the ex- 
tended memory feature. 



2.72 .RDBDF {XM Only) 



The .RDBDF macro defines the symbolic offset names for the region defini- 
tion block and the names for the region status word bit patterns. In addi- 
tion, this macro also defines the length of the region definition block by 
setting up the following symbol: 

R.GLGH - 6 

The .RDBDF macro does not reserve space for the region definition block. 

Macro Call: .RDBDF 

The .RDBDF macro expands as follows: 



R.GID 


= 


R.GSIZ 


= 2 


R.GSTS 


= 4 


R.GLGH 


= 6 


RS.CRR 


= 100000 


RS.UNM 


= 40000 


RS.NAL 


= 20000 



2.73 .READ/.READC/.READW 

Read operations for the three modes of RT-11 I/O are done using the 
.READ, .READC, and READW programmed requests. 
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In the case of .READ and .READC, additional queue elements should be 
allocated for buffered I/O operations (see the .QSET request). 

Upon return from any .READ, .READC, or .READW programmed request, 
RO contains the number of words requested if the read is from a sequential- 
access device (for example, paper tape). If the read is from a random-access 
device (disk or DECtape), RO contains the actual number of words that will 
be read (.READ or .READC) or have been read (.READW). This number is 
less than the requested word count if an attempt is made to read past end- 
of-file, but a partial transfer of one or more blocks is possible. In the case of 
a partial transfer, no error is indicated if a read request is shortened. 
Therefore, a program should always use the returned word count as the 
number of words available. 

For example, suppose a file is five blocks long (it has block numbers to 4) 
and a request is issued to read 512(decimal) words, starting at block 4. 
Since 512 words is two blocks, and block 4 is the last block of the file, this is 
an attempt to read past end-of-file. The monitor detects this and shortens 
the request to 256(decimal) words. On return from the request, RO contains 
256, indicating that a partial transfer occurred. Also, since the request is 
shortened to an exact number of blocks, a request for 256 words either 
succeeds or fails, but cannot be shortened. 

An error is reported if a read is attempted starting with a block number 
that is beyond the end-of-file. The carry bit is set, and error code appears 
in byte 52. No data is transferred in this case, and RO contains a zero. 

.READ 

The .READ request transfers to memory a specified number of words from 
the device associated with the specified channel. The channel is associated 
with the device when a .LOOKUP or .ENTER request is executed. Control 
returns to the user program immediately after the .READ is initiated, pos- 
sibly before the transfer is completed. No special action is taken by the 
monitor when the transfer is completed. 

Macro Call: .READ area,chan,buf,wcnt,blk 
where: 

area is the address of a five-word EMT argument block 

chan is a channel number in the range 0-376(octal) 

buf is the address of the buffer to receive the data read 

went is the number of words to be read 

blk is the block number to be read. For a file-structured 
.LOOKUP, the block number is relative to the start of the 
file. For a non-file-structured .LOOKUP, the block number is 
the absolute block number on the device. Note that the first 
block of a file or device is block number 0. The user program 
normally updates hlk before it is used again. If input is from 
TT: and blk = 0, TT: issues an uparrow C) prompt (This is true 
for all .READ requests.) 
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Notes: 

1. .READ and .RE ADC requests instruct the monitor to do a read from the 
device by queuing a request for the device and immediately returning 
control to your program. 

2. .READ and .READC requests execute as soon as all previous I/O re- 
quests to the device handlers have been completed. Note that a read 
from RKl: must wait for a previous read from RKO: to complete. This is 
a hardware restriction common to most disks because the controller 
looks at all I/O operations sequentially. 

3. Read errors are returned from the .READ and .READC or the .WAIT 
request. Errors can occur on the read or on the wait, but only one error 
is returned. Therefore, the program must check for an error when the 
read is complete (.READ/BCS) and after the wait (.WAIT/BCS). The 
wait request returns an error, but it does not indicate which read 
caused the error. 

Errors reported on the return from the read request are as follows: 

a. Nonexistent device/unit 

b. Nonexistent block 

c. In general, errors that do not require data transfers but are control- 
ler errors or EOF errors 

4. During the .READ and .READC requests, the monitor keeps track of 
errors in the channel status word. If an error occurs before the monitor 
can return to the caller, the error is reported on the return from the 
read request with the carry bit set and the error value in RO. If the 
error occurs after return from the read request, the error is reported on 
return from the next .WAIT, or the next .READ/.READC. Some errors 
can be returned from .READ/.READC requests immediately, before any 
I/O operation takes place. One condition that causes an immediate er- 
ror return is an attempt to read beyond end-of-file. 

5. If .READ/C/W requests are used to receive messages under a system job 
monitor, the buffer must be one word longer than the number of words 
expected to be read. Upon completion of the data transfer, the first word 
of the buffer will contain a value equal to the number of words actually 
transferred (as for .RCVD/C/W). 

Request Format: 

RO — > area: 



10 



Chan 



blk 



buf 



went 



When the user program needs to access the data read on the specified 
channel, a .WAIT request should be issued as a check that the data has 
been read completely. If an error occurred during the transfer, the .WAIT 
request indicates the error. 
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Errors: 

Code 

1 
2 

Example: 



Explanation 

Attempt to read past end-of-file. 
Hard error occurred on channel. 
Channel is not open. 



.TITLE READ. MAC 
+ 
.READ / .WRITE - This is an example in the use of the .READ / .WRITE 
re=iuests. The example demonstrates asynchronous I/O where a mainline 
prosram initiates input uia .READ re^iuestsi does some other prooessin: 
maKes sure input has completed uia the .WAIT rei^uesti then outputs 
the blooK Just read. Another .WAIT is issued before the next read 
is issued to make sure the preuious write has finished. This example 
is another sinale file copy prosrami utilizins .CSIGEN to input the 
file specs I load the re>iuired handlers and open the files. 



START: 



1$: 



.MCALL 
.MCALL 

ERRBYT 

.ENABL 
.CSIGEN 

Moy 

CLR 

.READ 

BCS 

i 

BIT 

BNE 

.PRINT 



. READ I .WRITE . .CLOSE i . PRINT 
.CSIGEN 1. EX IT ..WAIT..SRESET 



= 52 

LSB 

»DSPACE.«DEFEXT 

OAREA.R5 

lOBLK 

R5 («3 

S$ 

ol iIOBLK 

Z$ 

«MESSG 



iError Byte location in SYSCOM 

iEnable local symbol blocK 

iUse CSIGEN to Set handlersj files 

iR5 => EMT ArSuiiient list 

iStart reads with BlocK »0 

iRead a blocK . . . 

JBranch on error 

iThen simulate 

S some other 

imeaninsf ul (?) 

iproces s . . . 



2$: 



3$: 
at: 



5i: 
S$: 



7t: 



M n c n i • 

lOBLK: 



BUFF: 

DEFEXT: 

DONE: 

MESSG: 

WERR: 

RERR: 

DSPACE: 



.WAIT 

BCS 

.WRITE 

BCS 

INC 



.WAIT 

BCC 

MOM 

.PRINT 

BR 

MOM 

BR 

TSTB 

BNE 

.PRINT 

.CLOSE 

.SRESET 

.EXIT 

t nuRD 

.WORD 

.WORD 

.WORD 

.WORD 

.BLKW 

.WORD 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.EMEN 



.END 



«3 
5* 

R5 i«0 
3$ 
lOBLK 



«0 
1$ 
ttWERRiRO 

7* 
sRERRiRO 

at 

8«ERRBYT 
5* ' 
«DONE 
«0 





BUFF 

Z5B. 



25B. 

lO lO (0 

/I-O Transfer Complete/ iMessaSes... 

<15><12>/< SimulatinS Mainline Processins >/ 

/?Wri te Er ro r?/ 

/?Read Erro r?/ 



iDid read finish OK? 

iBranch if not (must be hard error!) 

iNou write the blooK Just read 

iB ranch on error 

iBump BlocK « 

iWe could do some more processing here 

Wait for write to finish 

Branch if write was successful 

RO => Write error ms3 

Repo rt error 

MerSe to exit proSram 

RO => Read error ms S 

Branch to report error 

Read error... EOF? 

Br an oh if not 

Yes 1 .. announce completion 

MaKe output file permanent 

Dismiss fetched handlers 

then exit pro sram 

EMT Area blocK 

BlocK a I 

Buffer addr & word count 

already fixed in blocK... 

I/O buffer 

No default extensions for CSIGEN 



iHandlers may be loaded startinS here 



START 
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.READC 

The .READC request transfers a specified number of words from the indi- 
cated channel to memory. Control returns to the user program immediately 
after the .READC is initiated. Attempting to read past end-of-file also 
causes an immediate return, in this case with the carry bit set and the error 
byte set to 0. Execution of the user program continues until the .READC is 
complete, then control passes to the routine specified in the request. When 
an RTS PC is executed in the completion routine, control returns to the 
user program. 

Macro Call: .READC area,chan,buf,wcnt,crtn,blk 



where: 



area 
chan 
buf 



is the address of a five-word EMT argument block 

is a channel number in the range 0-3 7 6 (octal) 

is the address of the buffer to receive the data read 



went is the number of words to be read 

crtn is the address of the user's completion routine. The address of 
the completion routine must be above 500(octal) 

blk is the block number to be read. For a file-structured 
.LOOKUP, the block number is relative to the start of the 
file. For a non-file-structured .LOOKUP, the block number is 
the absolute block number on the device. The user program 
normally updates blk before it is used again 

When a completion routine is called, error or end-of-file information for a 
channel is not cleared. The next .WAIT or .READ/.READC on the channel 
(from either mainline code or a completion routine) produces an immediate 
return with the C bit set and the error code in byte 52. The completion 
routine will never be entered if the .READC request returns an error. 

Request Format: 

RO -^ area: 



10 



chan 



blk 



buf 



went 



crtn 



When a .READC completion routine is entered, the following conditions are 
true: 

1. RO contains the contents of the channel status word for the opera- 
tion. If bit of RO is set, a hardware error occurred during the 
transfer; consequently, the data may not be reliable. The end-of- 
file bit, bit 13, may be set. 

2. Rl contains the channel number of the operation. This is useful 
when the same completion routine is to be used for transfers on 
different channels. 
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On a file-structured transfer, a shortened read is reported when 
the .RE ADC request is returned, not when the completion routine 
is called. 

Registers RO and Rl can be used by the routine, but all other 
registers must be saved and restored. Data cannot be passed be- 
tween the main program and completion routines in any register 
or on the stack. 



Errors: 



Code Explanation 

Attempt to read past end-of-file; no data was read. 

1 Hard error occurred on channel. 

2 Channel is not open. 
Example: 



.TITLE 



READC.MAC 



.READC / .WRITC - This is an example in the use of the .READC / .WRITC 
requests. The example .ieiiionst rates eyent-driwen I/O where a mainline 
program initiates a file transfer and completion routines continue it 
while the mainline proceeds with other processes. The example is another 
sinsle file copy program » utilizing .CSIGEN to input the file specs i load 
the required handlers and open the files. 



START: 



1$: 



WERR: 

RERR: 
GBYE: 



WRDONE: 



lOXFER: 



2$: 

3$! 



.MCALL 

ERRBYT 

.ENABL 

.CSIGEN 

CALL 

.PRINT 

MDU 

DEC 

BNE 

TSTB 

BEO 

INCB 

BEO 

BLT 

.CLOSE 

MOU 

BR 

MOU 

BR 

MO I.' 

.PRINT 

.SRESET 

.EXIT 

.WAIT 

BCS 

.READC 

BCC 

TSTB 

BEQ 

DECB 

DECB 

RETURN 

.WAIT 

BCS 



.READC ,. WRITC ,. CLOSE ..PRINT ..CSIGEN. .EXIT ..WAIT ..SRESET 



= 52 

LSB 

»DSPACE .sDEFEXT 

lOXFER 

ttMESSG 

«-l .R5 

R5 

1$ 

EOF 

1$ 

EOF 

WERR 

RERR 

»0 

»DONE .RO 

GBYE 

ttWRERR (RO 

GBYE 

ttRDERR .RO 



«0 

3* 

«AREA ,*3 , . .#4$ 

7$ 

li«ERRBYT 

G$ 

EOF 

EOF 



#3 
2$ 



iError Byte location in SYSCDM 

iUse CSIGEN to Set handlers, files 

iStart I/O 

i N w simulate other mainline process 

J 

i (kill some time) 

i 

iDid I/O complete? 

! N . 1 . d some more mainline w o r K 

iCheck for read/ write error 

lEDF = = Write error 

iEOF < = Read error 

iEOF > = End of File 

iRO => We're done messS 

iMerSe to exit proSraw 

iSet UP error messages here... 



Print m e s s a S e 

Dismiss fetched handlers 

Exit proSram 

Write c m p 1 r t n e . . . w r i t e successful' 

Branch if not... 

Queue up a read 

Branch if oK... 

Error - is it EOF? 

Branch if yes 

User EOF FlaS to indicate hard error 

EOF = -2 Read err / = -1 Write err 

Leaue completion code 

Compl rtne »2 - was read ok? 

Br an oh if not 
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.WRITC 




BCS 


5$: 


INC 




RETURN 


6$: 


INCB 


7*: 


RETURN 


AREA: : 


.WORD 


BLOK: 


.WORD 




.WORD 




.WORD 




.WORD 


BUFF: 


.BLKW 


DEFEXT: 


.WORD 


DONE: 


.ASCI2 


MESSG: 


.ASCIZ 


WRERR: 


.ABCIZ 


RDERR: 


.ASCIZ 


EOF: 


.BYTE 




.E'.'EN 


DSPACE 


= , 



*AREAi«Oii(»WRDONE iQueue up a yrite... 

3* iB ranch if error 

BLOK iBump block « for next read 

iLeaue Completion code... 
EOF iSet EOF flaS 

I then ret u rn 
iEMT Area blocK 

iBlocK « t 

BUFF iBuffer addr & word count 

25G. ialready fixed in blocK... 

iCoMPletion rtne addr 

25G. iI/0 buffer 

OiOiO.O iNo default extensions for CBIGEN 

/I-O Transfer Complete/ iMessaSes... 
/< SimulatinS Mainline Processing >/ 
/?Write Erro r?/ 
/?Read Error?/ 
iEOF flas 



iHandlers may be loaded startinS here 



.END 



START 



.READW 

The .READW request transfers a specified number of words frona the indi- 
cated channel to memory. When the .READW is complete or an error is 
detected, control returns to the user program. 

Macro Call: .READW area,chan,buf,wcnt,blk 

where: 

area is the address of a five-word EMT argument block 

chan is a channel number in the range 0-376(octal) 

buf is the address of the buffer to receive the data read 

went is the number of words to be read; each .READ request can 
transfer a maximum of 32K words 

blk is the block number to be read. For a file-structured 
.LOOKUP, the block number is relative to the start of the 
file. For a non-file-structured .LOOKUP, the block number is 
the absolute block number on the device. The user program 
normally updates blk before it is used again 

Request Format: 

RO -^ area: 



10 chan 



blk 



buf 



went 







If no error occurred, the data is in memory at the specified address. In an . 
FB environment, the other job can be run while the issuing job is waiting 
for the I/O to complete. 
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If a volume is opened with a non-file-structured lookup and the word count 
specified is greater than the number of words left on the volume, .READW 
returns a hard error. 



Errors: 

Code 

1 
2 

Example: 



Explanation 

Attempt to read past end-of-file. 
Hard error occurred on channel. 
Channel is not open. 



■TITLE READW. MAC 
(■ 

.READW / .WRITW - This is an example in the use of the .READW / .WRITW 
requests. The example is a single file copy prosram. The file specs 
are input from the console terminalt and the input & output files opened 
uia the Seneral mode of the CBI. The file is copied usins synchronous 
I/Oi and the output file is made permanent via the .CLOSE request. 



START: 



READ: 



1$! 
2*: 



3*: 



a$: 



DEXT: 
AREA: 
lOBLK: 



BUFFR 
RERR 
WERR 
DONE 



.MCALL 

ERRBYT=52 

.CSIGEN 
CLR 
MOy 
.READW 



BCC 

TSTB 

BEO 

MOM 

.PRINT 

BR 

.WRITW 

INC 

BCC 

Moy 

BR 

.CLOSE 

.PRINT 

.SRESET 

.EXIT 

.WORD 

.WORD 

.WORD 

.WORD 

.WORD 

■ WORD 

.BLKW 

.ftSCIZ 

.ASC12 

.ASCIZ 

. EVEN 



. CSIGEN I. READW I .PR INT 1, EX IT .. WRITW ., CLOSE i .SRESET 
lError Byte Location 



sDSPACE i«DEXT 
lOBLK 
«AREAiR5 
R5.S3 



2* 

e«ERRBYT 
3* 
«RERR (RO 

at 

R5.»0 

lOBLK 

READ 

sWERRiRO 

1* 

«0 

aDONE 



,0 ,0 .0 





BUFFR 

258. 



25G. 

/? Read e rro r ?/ 

/? Write error ?/ 

/I-O Transfer Complete/ 



Get strinS from terminal 

Input blocK * starts uith 

R5 => EMT Arsument list 

Read a block on Channel 3 

B1K«( Buff addr & WC already in ar3 

blk! 

B ranch if no errors 

Is error EOF? 

Yes. . , 

RO => Read Error Message 

Print the messaSe 

Exit p ro d r am 

Write the blocK Just read 

Bump block « (doesn't affect C bit) 

Branch if no error 

RO => Write error message 

Branch to output the message 

End-of -Fi le ... Close output channel 

Announce successful copy 

Release handler(s) from memory 

Ex it the prosram 

No default extensions 
EMT Argument block 
Block » 

I/O Buf f e r add r 
Word Coun t 

I/O Buffer 



DSPACE: 



iHandlerfs) can be loaded starting 
ihe re 



.END 



START 
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2.74 .RELEAS 

See .FETCH/.RELEAS (Section 2.34). 

2.75 .RENAME 

The .RENAME request changes the name of the file specified. 

Macro Call: .RENAME area,chan,dblk 

where: 

area is the address of a two-word EMT argument block 

chan is an unused channel number in the range 0-376(octal) 

dblk is the address of a block that specifies the file to be renamed 
followed by the new file name 

Request Format: 

RO —> area: 



4 chan 



dblk 



The dblk argument consists of two consecutive Radix-50 device and file 
specifications. For example: 



DBLK 



.RENAME 


«AREA »«7 ,«DBLK 


;USE CHANNEL 7 


BCS 


RNMERR 


iNOT FOUND 


,RAD50 


/DT3/ 




.RAD50 


/DLDFIL/ 




.RAD50 


/MAC/ 




,RAD50 


/DT3/ 




.RAD50 


/IMEWFIL/ 




.RAD50 


/MAC/ 





The first string represents the file to be renamed and the device where it is 
stored. The second represents the new file name. If a file with the same 
name as the new file name specified already exists on the indicated device, 
it is deleted. The second occurrence of the device name DT3 is necessary for 
proper operation and should not be omitted. The specified channel is left 
inactive when the .RENAME is complete. .RENAME requires that the han- 
dler to be used be resident at the time the .RENAME request is made. If it 

io «/-\f o TvirM-iif m- £ifT«rif nnntnra XTr\fo fViof RTT.IST A TV/TTh^. to lorrol rM^lxT r\irt -filoo ^»T^ 

JLU ±±\jyjj t4. i.XX\JXXl.U\JX V/J. X WJ. V^V/V^V*.J. U. AIV^UN^ UJLAL4.U . JL VJL^ J. ^ X X.X.1 J. JL-i iU X^.'^LAX V^XXXJ" V^XX XXXV^k^T \_fXX 

block-replaceable devices (disks and DECtape). In magtape operations, the 
handler returns an illegal operation code in byte 52 if a .RENAME request 
is attempted. A .RENAME request to other devices is ignored. 

Files cannot be protected or unprotected using the .RENAME request. To 
change the protection status of a file, use the .FPROT request or the PRO- 
TECT and UNPROTECT commands. 

File dates can be changed using the .SFDAT request. 
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Errors: 



Code 


1 
2 
3 



Example: 



Explanation 

Channel open. 

File not found. 

Invalid operation. 

A file by that name already exists and is protected. 
A RENAME was not done. 



.TITLE RENAME.MflC 



.RENAME - This is an SKample in the use of the .RENAME request. 
The example renames a file aooordins to filespeos input thru the 
.CSISPC request. 



2.76 





.MCALL 


.RENAME. .PRINT. 


EXIT 






.MCALL 


.CSISPC. .FETCH. 


SRESET 






ERRBYT 


= 52 




.Error byte location 


START: 


.CSISPC 


eFILESP.aDEFEXT 




iUse .CSISPC to Set file specs 




.FETCH 


«HANLOD.»FILESP 




iGet Handler from outspec 




BCS 


2* 




.Branch if failed 




MOU 


SFILESP.R2 




iR2 => Outspeo 




MOU 


•FILESP+4G ,R3 




!R3 => Inspeo 




MOU 


eR2.FILESP+3B 




iCopy device spec to in spec 




.REPT 


4 




iCopy outspec behind in spec 




MOM 


(R2)+,(R3)+ 




Sfor .RENAME. , , 




.ENDR 










.RENAME 


»AREA.»0 ,«FILESP+3G 


.Rename input file 




BCC 


1* 




iOperation successful 




DECB 


SeERRBYT 




.MaKe error code -1.0 or +i 




BEO 


3$ 




.Branch if F i 1 e - N o t - F o u n d 




MOU 


•ILLDP. RO 




illlesal operation -set up msS 




BR 


5* 




.Branch to report error 


1$: 


.SRESET 
.EXIT 






.Dismiss handlers 
.Exit program 


2$: 


MOU 


• NOHAN ,R0 




.Fetch failed-set up messaSe 




BR 


5* 




.Branch to report error 


3*: 


MOU 


•NOFIL, RO 




.File not found-setup message 


5$: 


.PRINT 






.Print error messase 




BR 


1$ 




.Then exit uia .SRESET 


AREA: 


.BLKW 


5 




lEMT Argument blocK 


DEFEXT: 


.WORD 


0,0.0.0 




.No default extensions 


NOFIL: 


.ASCIZ 


/?Fiie not found 


?/ 


.Error messaSe text 


ILLDP: 


.ASCIZ 


/?1 1 lesal Ope ration?/ 




NOHAN: 


.ASCIZ 
.EUEN 


/?. FETCH Failed? 


/ 




FILESP: 


.BLKW 


38, tZ 




iCSISPC Input Area 


HANLDD 


.END 


START 




.Handlers can load here... 


.REOPEN 











The .REOPEN request associates the channel that was specified with a file 
on which a .SAVESTATUS was performed. The .SAVESTATUS/.REOPEN 
combination is useful when a large number of files must be operated on at 
one time. As many files as are needed can be opened with .LOOKUP, and 
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their status preserved with .SAVESTATUS. When data is required from a 
file, a .REOPEN enables the program to read from the file. The .REOPEN 
need not be done on the same channel as the original .LOOKUP and 
.SAVESTATUS. 



Macro Call: 

where: 

area 
chan 
cblk 



.REOPEN area,chan,cblk 

is the address of a two-word EMT argument block 

is a channel number in the range 0-376(octal) 

is the address of the five-word block where the channel status 
information was stored 



Request Format: 
RO -^ area: 

Errors: 



chan 



cblk 



Code Explanation 

The specified channel is in use. The .REOPEN has not been 
done. 

Example: 

Refer to the example for the .SAVESTATUS request. 

2.77 MSUM (FB and XM Only) 

See .SPND/.RSUM (Section 2.89). 

2.78 .SAVESTATUS 

The .SAVESTATUS request stores five words of channel status information 
into a user-specified area of memory. These words contain all the informa- 
tion RT-11 requires to completely define a file. When a .SAVESTATUS is 
done, the data words are placed in memory, the specified channel is freed, 
and the file is closed. When the saved channel data is required, the 
.REOPEN request is used. 

.SAVESTATUS can only be used if a file has been opened with .LOOKUP. 
If .ENTER was used, .SAVESTATUS is invalid and returns an error. Note 
that .SAVESTATUS is not valid for magtape or cassette files. 

The .SAVESTATUS/.REOPEN requests are used together to open many 
files on a limited number of channels or to allow all .LOOKUPS to be done 
at once to avoid USR swapping. 

While the .SAVESTATUS/.REOPEN combination is useful, care must be 
observed when using it. In particular, the following cases should be 
avoided: 
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1. If a .SAVESTATUS is performed and the same file is then deleted 
before it is reopened, it becomes available as an empty space that 
could be used by the .ENTER command. If this sequence occurs, 
the contents of the file supposedly saved changes. 

2. Although the device handler for the required peripheral need not 
be in memory for execution of a .REOPEN, the handler must be 
in memory when a .READ or .WRITE is executed, or a fatal error 
is generated. 

One of the more common uses of .SAVESTATUS and .REOPEN is to con- 
solidate all directory access motion and code at one place in the program. 
All files necessary are opened and their status saved, then they are re- 
opened one at a time as needed. USR swapping can be minimized by lock- 
ing in the USR, doing .LOOKUP requests as needed, using .SAVESTATUS 
to save the file data, and then unlocking the USR. The user should be 
aware of the consequences of locking in the USR in a foreground/back- 
ground environment. If the background job locks in the USR when the 
foreground job requires it, the foreground job is delayed until the back- 
ground job unlocks the USR. 

Macro Call: .SAVESTATUS area,chan,cblk 

where: 

area is the address of a two-word EMT argument block 

chan is a channel number in the range 0-376(octal) 

cblk is the address of the five-word user memory block where the 
channel status information is to be stored 



Request Format 
RO 



area: 



chan 



cblk 



The five words returned by .SAVESTATUS contain the following informa- 
tion: 



Name 


Offset 


Contents 


c.csw 





Channel status word 


C.SBLK 


2 


Starting block number of this file, 
or if non-file-structured 


C.LENG 


4 


Length of file 


C.USED 


6 


Highest block written 


C.DEVQ 


10 


Number of pending requests 


C.UNIT 


11 


Device unit number 


Errors: 






Code 




Explanation 



The channel specified is not currently associated with any 
files; that is, a previous .LOOKUP on the channel was never 
done. 
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Example: 



The file was opened with an .ENTER request, or a .SAVE- 
STATUS request was performed for a magtape or cassette 
file. 



.TITLE SAFEST. MAC 

f 
.SftyESTATUS / .REOPEM - This is an example in the use of the .BAUESTATUS 
/.REOPEN requests. These requests are most commonly used together to 
consolidate access to the USR at one place in the proSram or if the 
proSrain must access more files than there are I/O channels available. 
Once a channel has been opened i its status may be sauedi to be re-opened 
and used later as needed. This example merses 2-6 files into 1 filei 

-readins all input files on one channel. 





.MCALL 
.MCALL 


.CSIGEN 1 .SAMESTATl 
.READW. .WRITW ..PR 




ERRBYT 


= 52 


START: 


.CSIGEN 


»DSPACE.»DEFEXT 




MOM 


»3,R4 




MOM 


SAREA.R3 




MOM 


SSAMBLK.R5 


1$: 


.SAMEST 


R3 .R4 .R5 




BCS 


2* 




ADD 


ttl2.R5 




INC 


R4 




CMP 


«e. .Ra 




BGE 


■ 1* 


2$: 


MOM 


SSAMBLK .R5 




BEO 


7$ 


4t: 


.REOPEN 


R3 ,«3,R5 




CLR 


BLK 


5$: 


.READW 


R3 .»3,»BUFFR ,«256 




BCC 


G* 




TSTB 


esERRBYT 




BNE 


S» 




.PURGE 


«3 




ADD 


»12,R5 




TST 


SRS 




BNE 


ai 




•CLOSE 


«0 




.PRINT 


«DONE 




.EXIT 




B$: 


.WRITW 


R3,»0.«BUFFR,«25G 




INC 


WBLK 




INC 


BLK 




BCC 


5$ 




MOM 


ftWERR.RO 




BR 


S* 


7$: 


MOM 


SNDINP iRO 




BR 


9* 


8$! 


MOM 


SRERR.RO 


3$: 


.PRINT 
.EXIT 




AREA: 


.BLKW 


5 


BLK: 


.WORD 





WBLK: 


.WORD 





SAVBLK: : 


.BLKW 


30, 


DEFEXT: 


.WORD 


0.0,0,0 


NOINP: 


.ASCIZ 


/?No input files?/ 


WERR: 


.ASCIZ 


/?Write Error?/ 


RERR: 


.ASCIZ 


/?Read Error?/ 


DONE: 


.ASCIZ 
.EMEN 


/I-O Transf e r Comp 


BUFFR: 


.BLKW 


258. 


DSPACE 


= , 





3, .REOPEN, .CLOSE, .EXIT 
MT,, PURGE 

.Error byte loo in SYSCOM 

iGet file specs lopen files, load handlers 

iRa = 1st input channel 

iR3 => EMT Argument blocK 

iR5 => Channel sauestatus blocks 

iSave channel status 

iBranch if channel neuer opened 

iAdJust R5 to point to next status blocK 

iBump R4 to = next input channel 

iDone all input channels? 

iBranch if not 

!R5 -> to Ist saved channel status 

iBranch if no input files 

!Re-open input channel on Ch 3 

iStart readinS with block 
iBLK iRead a block 

iBranch if no error 

iCheok if error = EOF 

iBranch if not EOF 

iClear input channel for re- use 

iPoint R5 to next saved oh status 

iAny more input channels? 

iBranch if yes 

iWe're done. ..close output channel 

iAnnounce mer^e complete 

iExit program 
iWBLK iWrite block Just read 

iBump to next output block 

isame for input blk (doesn't affect C bit) 

iBranch if no error on write 

iWrite error - RO => messase 

ime r de . . . 

iRO => No input files messaSe 

i m e r S e . . . 

iRO = > Read error ms 9 

iReport error 

ithen exit program 

iEMT Argument block 

! C u r r s n t read block 

iCurrent write block 

iSaved channel status area 

iNo default extensions for CSIGEN 

iError messases 



leted/ 



i I/O buf f e r 
iHandlers start here. 



.END 



START 



2-114 Programmed Request Description and Examples 



2.79 .SCCA 

The .SCCA programmed request: 

Inhibits a CTRL/C abort 

Indicates when a double CTRL/C is initiated at the keyboard 

Distinguishes between single and double CTRL/C commands 

CTRL/C characters are placed in the input ring buffer and treated as nor- 
mal control characters without specific system functions. The request re- 
quires a terminal status word address (addr) that is used to report consecu- 
tive CTRL/C input sequences. Bit 15 of the status word is set when consecu- 
tive CTRL/C characters are detected. The program must clear that bit. An 
.SCCA request with a status word address of disables the intercept and 
reenables CTRL/C system action. 

Normally, the .SCCA request affects only the job currently running. When 
the program exits, CTRL/C aborts are automatically reenabled. However, if 
your FB or XM monitor includes global SCCA support enabled through 
system generation, you can choose to disable CTRL/C aborts throughout 
the system for as long as you need. Set the argument type to GLOBAL 
(type = GLOBAL) and set addr to any valid SCCA control word. Thereafter, 
all CTRL/C aborts will be inhibited until another global .SCCA request is 
issued to set addr to 0. Only background jobs can issue global .SCCA re- 
quests, and these do not affect foreground or system job operation. Global 
.SCCA requests issued by foreground and system jobs act as local .SCCA 
requests. 

There are three cautions to observe when using .SCCA: 

® The request can cause CTRL/C to appear in the terminal input stream, 
and the program must provide a way to handle it. 







The request makes it impossible to terminate program loops from the 
console; therefore, it should be used only in thoroughly tested, reliable 
programs. 

When .SCCA is in effect and the program enters an infinite loop, the 
system must be halted and rebootstrapped. 

® CTRL/C s from indirect command files or indirect control files are not 
intercepted by the .SCCA. 

Macro Call: .SCCA area,addr[,type = GLOBAL] 

where: 

area is the address of a two-word parameter block 

addr is the address of a terminal status word (an address of re- 
enables double CTRL/C aborts) 

type is the mode of SCCA operation. Type is an optional argument 
that selects either LOCAL (default) or GLOBAL .SCCA 
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Request format for LOCAL: 
RO 



area: 



35 







addr 



Request format for GLOBAL: 
RO -^ area: 



35 



addr 



Errors: 

None. 
Example: 



.MCALL 



.SCCfl . .EXIT .. PRINT . .GTLIN 











iProSram to prompt for a 










iname. User cannot CTRL/C 










iout until entering name. 


START: 


iSCCA 


»AREA 


.«ADDR.TYPE=GLOBAL 


iDi sabl e Cont ro 1/C 




.GTLIN 


SNAME 


.•PROMPT 


SPrompt for name 




,SCCA 


• AREA 


.«0,TYPE=GLOBAL 


iEnab 1 e Cont ro 1/C 




.EXIT 








AREA: 


,BLKW 


4 






ADDR: 


.WORD 









NAME: 


.BLKW 


12 






PROMPT: 


.ASCII 


/Ente 


r you r name /<200> 






.END START 







2.80 .SDAT/.SDATC/.SDATW (FB and XM Only) 

The .SDAT/.SDATC/.SDATW requests are used with the .RCVD/ 
.RCVDW/.RCVDC calls to allow message transfers between a foreground 
job and a background job under the FB or XM monitors. .SDAT transfers 
are similar to .WRITE requests, where data transfer is not to a peripheral 
but from one job to another. Additional I/O queue elements should be allo- 
cated for buffered I/O operations in .SDAT and .SDATC requests (see 
.QSET). 

Message handling in the FB monitor does not check for a word count of zero 
before queuing a send or receive data request. Since RT-11 distinguishes a 
send from a receive by complementing the word count, a .SDATW of zero 
words is treated as a .RCVDW of zero words. Thus, avoid a word count of 
zero at all times when using a .SDATW request. 

Be particularly careful if you use both synchronous (.RCVDW and 
.SDATW) and asynchronous (.RCVDC and .SDATC) requests in the same 
program. If you issue a mainline .SDATW while there is a pending 
.RCVDC, the .SDATW will wait until the .RCVDC is satisfied. If the com- 
pletion routine for the .RCVDC issues another .RCVDC, the mainline 
.SDATW will never complete. In general, you should avoid the use of both 
synchronous and asynchronous message requests in the same program. 



.SDAT 
Macro Call: 



.SDAT area,buf,wcnt 
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where: 

area is the address of a five-word EMT argument block 

buf is the buffer address of the beginning of the message to be 
transferred 

went is the number of words to transfer 

Request Format: 



RO 



area: 



25 







unused 



buf 



went 



Errors: 



Code 





Explanation 

No other job exists. (A job exists as long as it is loaded, 
whether or not it is aetive.) 



Example: 



i iSDAT/iRCyO - This is an example in the use of the i SDflT/ . RC'D 
i requests. The example is actually tuo prosramsi a BaokSround Job 
i which sends messages/ and a Foreground Jobi which reoeiues them. 
iNDTE: Each proSram should he assembled and linKed separately. 



.TITLE 
i Foresround Prosran 



SDflTF.MAC 



.MCALL 
STflRTF: .RCMD 



PRINT 



. RCMD,.MWflIT.,PRINT..EXIT 



FEXIT ! 

AREA: 

MBUFF: 

FGJDB: 
FMSG: 



.MWAIT 

TST 

BEO 

.PRINT 

.PRINT 

BR 

.EXIT 

.BLKW 

.BLKW 

.WORD 

.ASCIZ 

.ASCIZ 

.END 

.TITLE 



ttAREA isMBUFF )«40. 



sFGJOB 



MBUFF+Z 

FEXIT 

«FMSG 

• MBUFi^ + Z 

!3TARTF 



iRequest a messaSe up to BO char. 

iNo error possible - always a BG 

? 

iDo some other processing 

i 1 iKe announc ins FG act i ue . . . 



iWait for message to arrive... 

iNull messaSe? 

iYe5...exit the prosram 

iAnnounce we Sot the messase... 

I and echo it bacK 

iLoop to Set another one 



5 iEMT Arsument BlooK 

^1 • iBuf f er - Mas length + 1 

O iMaKe siire BO char messase ends ASCIZ 

/Hi - FG aliue and well and waitinS for a messaSe!,' 

/Hey BG - Got your messase it reads:/ 

STARTF 

STARTB.MAC 



i BaoKsround ProSraif, - Send a 'null' messase to step both programs 
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.MCALL 


.SDAT, 


.MWAIT,. 


GTLIN 


..EXIT, .PRINT 


STflRTB: 


CLR 


BUFF 






iCI ear 1 5 1 word 




.GTLIN 


«BUFF. 


UPRDMT 




iGet somethins to send to FG from TTY 




,St3AT 


»AREA. 


"BUFF .«ao. 


iSend input as messase to FG 




BCS 


1* 






iBranch on error - No FG 




.MWftIT 








iWait for message to be sent 




TST 


BUFF 






iSent a nul 1 messaSe? 




BNE 


STARTS 






?No...1qop to send an other message. 




.EXIT 








iYes ...exit pros ram 


1$: 


■PRINT 
.EXIT 


SNQFG 






iNo FG ! 

iEx it program 


flREft: 


.BLKW 


5 






iEMT Arsument BIooK 


BUFF: 


.BLKW 


tiO, 






iUp to 80 char messase 


PROMT: 


.ASCII 


/Ente r 


me ssaSe 


to be 


sent to FG Job/< 15X 12>/ >/<200> 


NOFG: 


.ASCIZ 
.END 


/?No FC 
STARTS 


?/ 






.SDATC 












Macro Call: .SDATC area,buf,wcnt, 


3rtn 



where: 

area is the address of a five-word EMT argument block 

buf is the buffer address of the beginning of the message to be 
transferred 

went is the number of words to transfer 

crtn is the address of the completion routine to be entered when 
the message has been transmitted 

Request Format: 

RO -^ area: 



25 







unused 



buf 



went 



crtn 



Errors: 

Code Explanation 

No other job exists. (A job exists as long as it is loaded, 
whether or not it is active.) 

Example: 

See the example following .SDATW. 
sn A 'vwT 
Macro Call: .SDATW area,buf,wcnt 

where: 

area is the address of a five-word EMT argument block 

buf is the buffer address of the beginning of the message to be 
transferred 

went is the number of words to transfer 
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Request Format 
RO 



Errors: 



Code 



Example: 



area: 



25 







unused 

buf 

went 





Explanation 

No other job exists. (A job exists as long as it is loaded, 
whether or not it is active.) 



.SDATW/RC'DW - This is an example in the use of the .SDATW/ . RCVDW 
requests. The example consists of two programs! a Foresround Job 
which creates a file and sends a message to a Background program 
which copies the FG channel and reads a record from the file. Both 
programs must be assembled and linked separately. 

.TITLE SDflTWF.MAC 



i This is the Foreground program ... 
i - 

.MCflLL .ENTER.. PRINT .. SDATW .. EXIT .. RCVDW .. CLOSE ..WRITW 



iR5 => EMT argument block 
{Create a 5 block file 
>»a iWrite a record BG is interested in 
iBranoh on error 
iSend message with info to BG 
»Do some other processing 
iWhen it's time to exiti make sure 
iBG is done with the file 
iTell user we're exiting 
iExi t the pro gram 
iPrint error message 
ithen exit 
iFile spec for .ENTER 

iEMT argument block 

iChannel « 

iBlock s 

jFi le record 

lError message text 

iExi t message 



.TITLE SDATWB.MAC 
i + 

i This is the Background program ... 
! - 

.MCALL .CHCOPY . .RCVDW . .READW .. EXIT .. PRINT i .SDATW 



iR5 => EMT arg block 
iWait for message from FG 
iBranoh if no FG 

iChannel « is Ist word of message 
iBranoh if FG channel not open 
iMSG+a iRead block which is 2nd word of msg 
iBranch if read error 
iContinue processing... 
iTell FG we're thru with file 
iTell userue're thru 
ithen exit p rogram 



STARTF! 


MOV 


»AREA,R5 




.ENTER 


R5.»0.ttFILE,»5 




.WRITW 


R5.«0.«RECRD,»25B 




BCS 


ENTERR 




.SDATW 


R5.«BUFR.«2 




1 

.RCVDW 


R5.»BUFRi»l 




.CLOSE 


«0 




.PRINT 


•FEXIT 




.EXIT 




ENTERR: 


.PRINT 
.EXIT 


»ERMSG 


FILE: 


.RAD50 


/DK OUFILE/ 




.RAD50 


/TMP/ 


AREA: 


.BLKW 


5 


BUFR: 


.WORD 







.WORD 


a 


RECRD: 


.BLKW 


25G. 


ERMSG: 


.ASCIZ 


/?Enter Error?/ 


FEXIT: 


.ASCIZ 


/FG Job exiting/ 




.END 


STARTF 



STARTS: 


MOV 


»AREA,R5 




.RCVDW 


R5.SMSG .»Z 




BCS 


1* 




.CHCOPY 


R5.«0.MSG + Z 




BCS 


2« 




.READW 


R5 .«0 i«BUFF i«25B 




BCS 


3$ 




.SDATW 


R5.«MSG,»1 




.PRINT 


«BEXIT 




.EXIT 
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1$. MOy sNQJOBiRO iRO => No FG error msS 

BR 4$ iBranch to print msS 

2$: MOV sNOCH iRO iRO => FG ch not open msS 

BR 4$ iB ranch t . . 

3$: MOV sRDERRiRO SRO => Read err msS 

4$. .PRINT iPrint proper error msS 

.EXIT 1 then ex it I 

ftREfl: iBLKW 5 iEMT argument bIK 

MSG: .BLKW 3 iMessaSe buffer 

BUFF: .BLKW Z5B . !FiIe buffer 

BEXIT: .ftSCIZ /Chann e 1 -Re co rd copy successful/ 

NOJOB: .flSCIZ /?NoFGJob?/ iE r ro r me s s aSe s . . . 

NOCH: .ASCIZ /?FG channel not open?/ 

RDERR: .flSCIZ /?Read E r ro r?/ 

.END STflRTB 



2.81 .SDTTM 



The .SDTTM (Set date and time) request allows your program to set the 
system date and time. 

Macro Call: .SDTTM area,addr 

where: 

area is the address of a two-word EMT argument block 

addr is the address of a three-word block in user memory that con- 
tains the new date and time 

Request Format: 

RO — * area: 



40 



addr 



The first word of the three-word parameter block contains the new system 
date in internal format (see the .DATE programmed request). If this word 
is -1 (represents an illegal date), the monitor ignores it. Put a -1 in the 
first word of the parameter block if you want to change only the system 
time. If the first parameter word is positive, it becomes the new system 
date. Note that the monitor does no further checking on the date word. To 
be sure of a valid system date, you must specify a value between 1 and 
12(decimal) in the month field (bits 13-10) and a value between 1 and the 
month length in the day field (bits 9-5). Bits 14 and 15 must be zero. 

The second and third words of the parameter block are the new high-order 
and low-order time values, respectively. This value is the double-precision 
number of ticks since midnight. If the high-order time word is negative, the 
monitor ignores the new time. Put a negative value in the second word of 
the parameter block if you want to change only the system date. If the 
second parameter word is positive, the new time becomes the system time. 
The monitor does no further checking on the new time. To be sure of a valid 
system time, you must specify a legal number of ticks for the system line 
frequency. For a 60 Hz clock, the high-order time may not be larger than 
117(octal), and if it is equal to 117, the low-order time may not be equal to 
or larger than 15000(octal). For a 50 Hz clock, the high-order time may not 
be larger than lOl(octal), and if it is equal to 101, the low-order time may 
not be equal to or larger than 165400(octal). 
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Changing the date and/or time has no effect on any outstanding mark time 
or timed wait requests. 

Errors: 

None. 

Example: 



.TITLE SDTTM.MftC 



i + 



i .SDTTM.MAC - This is an example in the use of the .SDTTM request. 
i The example is a Day 1 i 9ht/St anda rd Time utility - to switch the 
i current system time from Standard to Davlisht or uice uersai call 
i the prosram as a subroutine at the proper entry point. 





.MCALL 


.SDTTMi.PRIN 




.GLOBL 


STD.DALITE 


STD: 


COM 


HR 




NEG 


HR + 2 


DftLITE: 


.GTIM 


»AREA.«TIME 




CALL 


JADD 




.SDTTM 


sAREAisNEWDT 




.GTIM 


sAREA.BTIME 




RETURN 




NEWDT: 


.NORD 


-1 


TIME: 


.WORD 


0,0 


HR: 


.WORD 


3 




.WORD 


45700 


AREA: 


.WORD 


0,0 


JfiDD: 


Moy 


»HR,R4 




MOV 


«AREA,R3 




MOM 


«HR,R1 




MOM 


-(Ra) .R2 




ADD 


-(R3) ,R2 




MOV 


-(R4) ,R5 




ADC 


R5 




ADD 


-(R3) ,R5 




MOM 


RZ,-(R1 ) 




MOM 


R5,-(R1) 




RETURN 






.END 





PRINT, .EXIT, .GTIM 



iSwi tch to STD time . . . 

iMaKe one hr in clocK ticKs 

iGet the current time 

iAd Just +/- 1 hour 

iSet the new system time 

iForce date rcllouer (if any) 

iReturn to caller 

!. SDTTM arguments - No new date 
iNeu time 

iOne hour in clock tioKs (BO cycle 
i clocK ! ) 

iEMT Arsument BlocK 

iDouble precision inteser add 

iR4 => Low order of System time + 2 

iR3 => Low order of One hour + 2 

iRl => Low order of new time 

iPut low order of Ist operand in RZ 

iAdd in low order of operand »2 

!Put hish order of operand »1 in R5 

iAdd in carry (no overflow possible !) 

!Add in hish order of operand «2 

i (ditto ! ) 

iStore result where wanted 

iReturn to caller 



2.82 .SERB 

See .HERR/.SERR (Section 2.42). 

2.83 .SETTOP 

The .SETTOP request specifies a new address as a program's upper limit. 
The monitor determines whether this address is legal and whether or not a 
memory swap is necessary when the USR is required. For instance, if the 
program specified an upper limit below the start address of USR (normally 
specified in offset 266 in the resident monitor), no swapping is necessary, as 
the program does not overlay the USR. If .SETTOP from the background 
specifies a high limit greater than the address of the USR and a SET USR 
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NOSWAP command has not been given, a memory swap is required. The 
use of .SETTOP in an extended memory environment is described at the 
end of this section. 

Careful use of the .SETTOP request provides a significant improvement in 
the performance of your program. An approach that is used by several of 
the system-supplied programs is as follows: 

1. A .SETTOP is done to the high limit of the code in a program 
before buffers or work areas are allocated. If the program is 
aborted, minimal writing of the user program to the swap blocks 
(SWAP.SYS) occurs. However, the program is allowed to be re- 
started successfully. 

2. A user command line is now read through .CSISPC or .GTLIN. 
An appropriate USR swap address is set in location 46. Successive 
.DSTATUS, .SETTOP, and .FETCH requests are performed to 
load necessary device handlers. This attempts to keep the USR 
resident as long as possible during the procedure. 

3. Buffers and work areas are allocated as needed with appropriate 
.SETTOP requests being issued to account for their size. Fre- 
quently, a .SETTOP of #-2 is performed to request all available 
memory to be given to the program. This can be more useful than 
keeping the USR resident. 

4. If the process has a well-defined closing phase, another .SETTOP 
can be issued to cause the USR to become resident again to close 
files (the user should remember to set location 46 to zero if this is 
done, so that the USR again swaps in the normal area). On return 
from .SETTOP, both RO and the word in location 50(octal) contain 
the highest memory address allocated for use. If the job requested 
an address higher than the highest address legal for the request- 
ing job, the address returned is the highest legal address for the 
job rather than the requested address. 

When doing a final exit from a program, the monitor writes the 
program to the file SWAP.SYS and then reads in the KMON. A 
.SETTOP #0 at exit time prevents the monitor from swapping out 
the program to the swap blocks (SWAP.SYS) before reading in 
the KMON, thus saving time. This procedure is especially useful 
on a diskette system when indirect command files are used to run 
a sequence of programs. The monitor command SET EXIT 
NOSWAP also disables program swapping. 

Macro Call: .SETTOP addr 



where: 



addr is the address of the highest word of the area desired (the last 
. word the program will modify, not the first word it leaves 
untouched) 
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Notes: 

1. A program should never do a .SETTOP and assume that its new upper 
limit is the address it requested. It must always examine the returned 
contents of RO or location 50 to determine its actual high address. 

2. It is imperative that the value returned in RO or location 50 be used as 
the absolute upper limit. If this value is exceeded, vital parts of the 
monitor can be destroyed. 

Errors: 

None. 

Example: 

.TITLE SETTDP.MAC 



• SETTOP - This is an SKample in the use of the .SETTOP request. The 
sKampIe tries to obtain as much memory as possible usin3 the .SETTOP 
request) which will force the USR into a swapping mode. The .LOCK request 
will brinS the USR into memory (ouer the hish 2k of our little proSram !) 
and force it to remain there until an .UNLOCK is issued. 





.MCALL 


.LOCK. .UNLOCK . 


LOOKUP 






.MCALL 


.SETTOP ..PRINT 


.EXIT 






SYSPTR=5a 






iPointer to besinnins of RMON 


START: 


.SETTOP 


fisSYSPTR 




.Try to allocate all of memory (up to 
iRMON) 




.LOCK 






ibrins USR into memory 




.LOOKUP 


»AREA,»0.»FILE1 


iLOOKUP a file on channel 




BCC 


1$ 




.Branch if successful 


2$! 


.PRINT 


«LMSG 




iPrint Error Message 




.EXIT 






.then exit program 


1$: 


.PRINT 


SFIFND 




.Announce our success 




Moy 


•AREA.RO 




.RO => EMT ArSument BlocK 




INC 


@R0 




ilncrement low byte of Ist ars (chan tt ) 




MOV 


»FILE2.2(R0) 




iFill in pointer to new filespec 




.LOOKUP 






.Do the .LOOKUP from filled in ar3 blooK 
.pointed to by RO. 




6CS 


Z» 




iB ranch on error 




.PRINT 


SFZFND 




iSay we found it 




.UNLOCK 


_, 




inow release the USR 




.EXIT 






.and exit program 


AREA! 


.BLKW 


3 




iEMT Argument BlocK 


FILEl: 


.RAD50 
.RAD50 
.RAD50 


/DK/ 

/PIP / 
/SAV/ 




.A File we're sure to find 


FILE2: 


.RAD50 
.RAD50 
=RAD50 


/DK/ 

/TECO / 
/SAV/ 




iAnother file ue misht find 


LMSG! 


.ASCIZ 


/?Error on .LOOKUP?/ 


.Error messaSe 


FIFND: 


.ASCIZ 


/. ..Found PIP. SAV/ 




F2FND! 


.ASCIZ 

.EVEN 

.END 


/. ■ .Found TECO 
START 


SAW/ 





2.83.1 .SETTOP in an Extended Memory Environment 

You can enable the extended memory feature of the .SETTOP programmed 
request with the linker A^ option or the LINK command with the /XM 
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option (see Chapter 11 in the RT-11 System Utilities Manual or Chapter 4 
of the RT-11 System User's Guide). The RT-11 Software Support Manual 
describes in detail the .SETTOP request in an extended memory environ- 
ment. The .SETTOP request operates in privileged and virtual jobs as fol- 
lows: 

Privileged Jobs 

1. A .SETTOP that requests an upper limit below the virtual high 
limit of the program will always return the virtual high limit of 
the program. The virtual high limit is the last address in the 
highest PAR that the program uses. In this case, a value can 
never be returned below the job's virtual high limit. 

2. A .SETTOP that requests a job's upper limit above the program's 
virtual high limit will return the highest available address as 
follows: 

a. Either the address requested or SYSLOW-2 (last used ad- 
dress, SYSLOW is next address available) is returned, which- 
ever is lower. SYSLOW is defined as the start of the USR in 
the XM monitor. 

b. If the program's virtual high limit is greater than SYSLOW 
(the user program maps over the monitor or USR), the virtual 
high limit of the program will always be returned. 

Virtual Jobs 

1. As in privileged jobs, a .SETTOP request can never get less than 
the virtual high limit of the job. 

2. If a .SETTOP requests an upper limit greater than the virtual 
high limit, the following occurs: 

a. If the virtual high limit equals 177776, this value is returned 
since this is the address limit in virtual memory. Otherwise, 
a new region and window will be created. The size of the 
region and window will be determined by the argument speci- 
fied to the .SETTOP or by the amount of extended m^emory 
that is available, whichever value is smaller. The .SETTOP 
argument rounded to a 32-word boundary minus the high 
.LIMIT value for the program equals the size of the region 
and window (see the LINK chapter of the RT-11 System Util- 
ities Matiual and the RT-11 Software Support Manual for a 

1 .J. ^''i'U^ T TTl iTTm JJ'-.^-JLl 1^ J 1_J \ T^ 

aescripxion oi tne .xjiiviii airecbive in exieiiueu iiitsiiiury;. n 
there are no region control blocks, window control blocks, or 
extended memory available, the program's virtual high limit 
is returned. The .SETTOP request uses one of the region and 
window control blocks allocated to the user, thus one less 
block is available to the program if the linker /V option is 
used. 

b. Additional .SETTOP requests can only remap the original 
window created by the first .SETTOP. Thus, additional re- 
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quests will return an address no higher than that established 
by the first request and no lower than the program virtual 
high limit. An additional .SETTOP request whose argument 
is higher than the first request will cause the entire first 
window to be mapped. An additional .SETTOP request whose 
argument specifies a value below the virtual high limit elimi- 
nates the region and window. If another .SETTOP request 
then follows, it may create a new region and window. 



2.84 .SFDAT 



The .SFDAT programmed request allows a program to set or modify the 
creation date in a file's directory entry. Dates on protected as well as unpro- 
tected files can be changed. 

Macro Call: .SFDAT area, chan, dblk, date 

where: 

area is the address of a three-word EMT argument block 

chan is a channel number in the range 0-376 

dblk is the address of a four-word block containing a filespec in 
Radix-50 

date is the address of the new date, in RT-11 format If this argu- 
ment is #0, the system date is used; bits 14 and 15 are always 
set to 0, but no other check is made for an illegal date 

Request Format: 
RO -^ area: 



42 chan 



dblk 



date 



Errors: 

Code 



1 

2 

Example: 

Refer to the example for the .FPROT request. 



Explanation 

Channel in use 

File not found 

Invalid operation (device not file structured) 



2.85 .SFPA (Special Feature) 



The .SFPA request allows users with floating-point hardware to set trap 
addresses to be entered when a floating-point exception occurs. If no user 
trap address is specified and a floating-point (FP) exception occurs, a 
?MON-F-FPU trap occurs, and the job is aborted. 
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Macro Call: .SFPA area,addr 
where: 

area is the address of a two- word EMT argument block 

addr is the address of the routine to be entered when an exception 
occur? 

Request Format: 

RO — > area: 



30 



addr 



Notes: 

1. The user trap routine must save and restore any registers it uses. It 
exits with an RTI instruction. 

2. If the address argument is #0, user floating-point routines are disabled 
and the fatal ?MON-F-FPU trap error is produced by any further 
traps. 

3. In the FB environment, an address value of #1 indicates that the FP 
registers should be switched when a context switch occurs, but no user 
traps are enabled. This allows both jobs to use the FP unit. An address 
of #1 to the SJ monitor is equivalent to an address of #0. 

4. When the user routine is activated, it is necessary to re-execute an 
.SFPA request, as the monitor disables user traps as soon as one is 
serviced. It does this to prevent a possible infinite loop from being set 
up by repeated floating-point exceptions. 

5. If the FPU is being used, the instruction STST -(SP) is executed by the 
monitor before entering the user's trap routine. Thus, the trap routine 
must pop the two status words off the stack before doing an RTI. The 
program can tell if FP hardware is available by examining the configu- 
ration word in the monitor. 

Errors: 

None. 

Example: 



.TITLE SFPA. MAC 



i + 



i .SFPA - This is an example in the use of the .SFPA request. This 
i example is a skeleton proSram which demonstrates how to set up a 
I Floating Point trap routinei and the minimum action that routine 
i must take before dismissing the error trap. 



START: 



.MCALL 



■ SFPA. .EXIT 



SYSPTR 


= 5a 


CONFIG 


= 300 


FPU 

i 

s 


= 100 



!Loo of beainninS of Monitor 
iOffset to Monitor oonf i su rat i on wd 
iFPU present bit 
iMainline program... 
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,SFPA «AREA i«FPTRfiP iSet up FPU error trap 

, icontinuemainlineproSrafit 

lEXIT iExitproSram 

FPTRAP: !FPU exception routine 

. iHandle exceptionttt 



CKFPU: MOy SsSYSPTR iRO iRO = > bas e of RMON 

BIT sFPll .CONFIG(RO) iCheok f o r FPU hdwe 

BEO 1* iBranoh if none 

CMP (SP)+i(SP)+ iMust POP status reSs off staoK! 

1$: RTI iBefore returning from interrupt 

.END START 



2.86 SOB 



The SOB macro simulates the SOB instruction (subtract one and branch if 
not equal) by generating the code: 

DEC register 
BNE location 

You can use the SOB macro on all processors, but it is especially useful for 
processors that do not have the hardware SOB instruction. If you are run- 
ning on a processor that supports the SOB instruction, simply eliminate the 
MACRO call to SOB (.MCALL SOB), and the SOB instruction executes. 
Note that SOB is not preceded by a dot (.). 

The SOB macro has the following syntax: 

SOB reg,addr 
where: 

reg is the register whose contents will be decremented by 1 

addr is the location to branch to if the register contents do not 
equal after the decrement 

In the following example, register RO is decremented by 1 and then tested. 
If the contents do not equal 0, the program branches to the label HERE. 

SOB Ra.HERE 



Note: The SOB instruction does not change any condition codes. The 
SOB macro can change the N, Z, and V (but not the C) condition 
codes. 

2.87 .SPCPS (FB and XM SYSGEN Option) 

The .SPCPS (save/set mainline PC and PS) request allows a program's 

completion routine to change the flow of control of the mainline code. 

I .SPCPS saves the mainline code PC and PS, and changes the mainline PC 

^ to a new value. If the mainline code is performing a monitor request, the 
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monitor allows that request to finish before doing any rerouting. The actual 
rerouting is deferred until the mainline code is about to run. Therefore, the 
.SPCPS request returns an error if it is reissued before an earlier request 
has been honored. Furthermore, the data saved in the user block is not 
valid until the new mainline code is running. 

The .SPCPS request is a system generation feature and is available only in 
FB and XM. If a program issues this call under SJ or under a monitor not 
generated for the call, no action is taken and no error is returned. 

Macro Call: .SPCPS area,addr 



where: 



area is the address of a two-word EMT argument block 

addr is the address of a three-word block in user memory that con- 
tains the new mainline PC, and that is to contain the old 
mainline PC and PS 



Request Format: 
RO -* area: 



41 



addr 



Errors: 

Code Explanation 

The program issued the .SPCPS call from the mainline code 
rather than a completion routine. 

1 A previous .SPCPS request is outstanding. 

When the program issues the .SPCPS request, the monitor saves the old 
mainline PS in the third word of the three- word block and the old mainline 
PC in the second word of the block. The monitor then changes the mainline 
PC to the contents of the first word of the block. 

Example: 





.TITLE 


SPCPS. MAC 




.ENftBL 


LC 


1 + 

J *SPCPS - 


This is an eKawple in the use of the .SPCPS request. In this 


» example 


.SPCPS is 


used to reroute the wainline code after an I/O 


; error or 


EOF is detected by a completion routine. 


! - 


.MCALL 


,READC,.WRITC,.CLOSE..PRINT..CSIGEN,.EXIT,.WftIT.,SRESET 




.MCflLL 


.SPCPS 




ERRBYT 


= 52 JError Byte location in SYSCOn 




.ENftBL 


LSB 


STftRT: 


.CSIGEN 


ttDSPACE iSDEFEXT SUse CSIGEN to Set handlers, files 




CALL 


lOXFER iStart I/O 




.PRINT 


sMESSG iNou simulate other mainline process 


1$: 


DEC 


R5 ! (Ki 1 1 some time) 




BR 


1* 


FINI: 


.CLOSE 


»0 !EOF > = End of File 




Moy 


•DONEiRO iRO^We'redonemessaSe 




BR 


GBYE iMerSe to exit proSram 


WERR: 


MOV 


«WRERR(RO iSet up error messages here... 




BR 


GBYE 


RERR: 


Moy 


• RDERR.RO 
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GBYE: 


.PRINT 




Print messaSe 




.SRESET 




Dismiss fetched handlers 




.EXIT 




Exit program 


WRDDNE: .WAIT 


ttO 


Write oompl rtne...urite successful? 




BCS 


3$ 


B ranch if not . . . 


lOXFER: .REflDC 


»AREAi»3, . .»G* 


Queue up a read 




BCC 


5$ 


B ranch if oK . . . 




TSTB 


e«ERRBYT 


Error - is it EOF? 




BEO 


at 


B ranch if yes 


2$: 


Moy 


»RERR. SBLOK 


Moue Read err rtne addr to arS blocK 




BR 


a% 


Merse. . , 


3$: 


Moy 


•WERR. SBLOK 


Moue Write err rtne addr to arS blocK 


a*! 


TSTB 


SPCALL 


Al ready done a .SPCPS? 




BNE 


5* 


Yes. ..don't do another 




.SPCPS 


»AREA.»SBLOK 


De-rail mainline code 




INCB 


SPCALL 


FlaS we'uB done this 




BCS 


7$ 


Ooops! Something's amiss! 


5$: 


RETURN 




Leaue completion code 


S$! 


.WAIT 


• 3 


Completion routine »2 - was read oK? 




BCS 


Z* 


Branch if not 




.WRITC 


»AREA.«0 , . .aWRDONE 


Oueue UP a write... 




BCS 


3$ 


Branch if error 




INC 


BLOK 


Bump blocK « for next read 




RETURN 




Leave Completion code... 


7*i 


.PRINT 
RETURN 


•SPERR 


Print .SPCPS failed message 


AREA: 


.WORD 





EMT Area block 


BLDK! 


.WORD 





BlocK «, 




.WORD 


BUFF 


Buffer addr & word count 




.WORD 


25B. 


al ready fixed in blocK . . . 




.WORD 





Completion routine addr 


SBLOK 


.WORD 


FINI .0.0 


.SPCPS Argument blocK (FINI default) 


BUFF: 


.BLKW 


25B. 


I/O buffer 


DEFEXT: .WORD 


0,0,0.0 


No default extensions for CSIGEN 


SPCALL: .BYTE 





.SPCPS called flaS in case I/O error 








(oompl rtne sets sched. resardless!) 




.NLIST 


BEX 




DONE: 


.ASCIZ 


/I-O Transfer Complete/ 


Messages . . . 


MESSG 


.ASCIZ 


/< Simulating Mainline Prooessins >/ 


WRERR 


.ASCIZ 


/?Write Erro r?/ 




RDERR 


.ASCIZ 


/?.Read Error?/ 




SFERR 


.ASCIZ 
.EVEN 


/?. SPCPS Error?/ 




DSPACE 


: = , 




Handlers may be loaded starting here 



2.88 .SPFUN 



.END 



START 



This request is used with certain device handlers to do device dependent 
functions, such as rewind and backspace. It can be used with diskettes and 
some disks to allow reading and writing of absolute sectors. This request 
can determine the size of a volume mounted in a particular device unit for 
RX02 diskettes, RD50/RD51 disks, RK06/RK07 disks, RL01/RL02 disks, 
MSCP disks, and logical disks. 

Macro Call: .SPFUN area,chan,func buf went blkr crtn^ 

where: 

area is the address of a six- word EMT argument block 

chan is a channel number in the range to 376(octal) 

func is the numerical code of the function to be performed; these 
codes must be negative 

buf is the buffer address; this parameter must be set to zero if no 
buffer is required 
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went is defined in terms of the device handler associated with the 
specified channel and in terms of the specified special func- 
tion code 

blk is also defined in terms of the device handler associated with 
the specified channel and in terms of the specified special 
function code 

crtn is the entry point of a completion routine. If left blank, is 
automatically inserted. This value is the same as for .READ, 
.READC, and .READW. 

- wait I/O (.READW) 

1 = real time (.READ) 

Value >500 = completion routine 
Request Format: 



RO -^ area: 



32 chan 



blk 



buf 



went 



func 377 



crtn 



The chan, blk, and went arguments are the same as those defined for 
.READ/.WRITE requests. They are only required when doing a .WRITE 
with extended record gap to magnetic tape. If the crtn argument is left 
blank, the requested operation completes before control returns to the user 
program. Specifying crtn as #1 is similar to executing a .READ or .WRITE 
in that the function is initiated and returns immediately to the user pro- 
gram. Use a .WAIT on the channel to make sure that the operation is 
completed. The crtn argument is a completion routine address to be entered 
when the operation is complete. 

The available functions and function codes for magtape and cassette are as 
follows: 

Function MM, MS, MT CT 

Forward to last file 377 

Forward to last block 376 

Forward to next file 375 

Forward to next block 374 

Rewind to load point 373 373 

Write file gap 372 

Write EOF 377 

Forward one block 3/6 

Backspace one block 375 

Write with extended 

file gap 374 

Off-line rewind 372 

Write 371 

Read 370 

Stream at 100 ips 

(MS only) 367 
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374 




374 






373 


373 


373 


373 
372 


373 

372 
371 



The available functions and function codes for diskettes, RK06/RK07 disks, 
RLOl and RL02 disks, the logical disk handler, MSCP disks, and 
RD50/RD51 disks are as follows: 

Function DX DZ DM DY DL LD DU DW 

Read 377 377 377 377 377 377 

Write 376 376 376 376 376 376 

Write with deleted 

data mark 375 375 

Force a read by the 

handler of the bad 

block replacement 

table from block 1 

of the disk 
Return device size 373 373 373 373 373 373 373 

Read/write translation 

table 
Direct MSCP access 

To use the .SPFUN request, the handler must be in memory and a channel 
must be associated with a file via a non-file-structured .LOOKUP request. 

A .SPFUN request to write absolute blocks on RX01/RX02 diskettes should 
not write anything in track if you want to use DUP or the COPY/DEVICE 
command to back up the volume. DUP does not copy data in track 0. Also, 
you should be careful to specify a valid buffer address and word count. The 
monitor checks that the huf argument is in the job area, but it does not 
check buf + went. If you use the .SPFUN request, and the device handler 
for that device does not support special functions or the particular .SPFUN 
code used, the call simply returns to the program without reporting an 
error. 

When using special functions 376 and 377 with DW or DZ: 

went is the track to be read or written. 

blk is the sector. 

buf is the address of a 256-word buffer. 

SPFUN 376 and 377 with DZ handler do not interleave sectors. RX50 disk- 
ettes, handled by DZ, have 80 tracks. SPFUN 376 and 377 wrap to track 
after track 79. 

When using special function 373 with DW: 

chan is the channel on which DW was opened with .LOOKUP. 

buf is the address of a one-word buffer in which the size of the 
volume will be returned: 9727(decimal) blocks for an RD50, 
19519(decim.al) blocks for an RD51. 

blk is not used and should be set to 0. 

For the RK06/07 handler (DM), special function codes 377 and 376 require 
the buffer size to be one word larger than necessary for the data. The first 
word of the buffer contains the error information returned as a result of the 
.SPFUN request. The data transferred as a result of the read or write 
request is found in the second and following words of the buffer. The error 
codes and information are as follows: 
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Code Meaning 

100000 The I/O operation is successful. 
100200 A bad block was detected (BSE error). 

100001 An ECC error is corrected. 

100002 An error recovered on retry. 

100004 An error recovered through an offset retry. 

100010 An error recovered after recalibration. 

1774xx An error did not recover. 

Other device-specific information is included in the RT-11 Software Sup- 
port Manual. 



Errors: 

Code 



1 
2 



Explanation 

Attempt to read or write past end-of-file, or invalid function 
value. 

Hard error occurred on channel. 

Channel is not open. 



Additional qualifying information for these errors is returned in the 
first two words of the blk argument status block. This information is 
given in Chapter 10 of the RT-11 Software Support Manual. 



Example: 



.TITLE SPFUN.MAC 



i iSPFUN - This is an sKample in the use of the iSPFUN request. The 
i esample reuinds a cassette and writes out a 253-uord buffer and 
i then a file 9ap. 



START: 



1$: 



.MCftLL 


.FETCH ..LOOKUP 


..SPFUN, .WRITW 


.MCftLL 


.EXIT 


..PRINT.. 


WAIT.. 


CLOSE 


.FETCH 


SHSPC 


,»CT 




iFetch the CT Handle r 


BCS 


1$ 






iBranoh if f ai led 


.LOOKUP 


«AREA 


rsa.ttCT 




iOpen channel 4 for output 


BCS 


2$ 






iBranch if error (should neuer hap- 
ipen ! ) 


.SPFUN 


SAREA 


,sa ,s373. 


SO 


iRewind to BOT usins Synchronous I/O 


BCS 


3$ 






iB ranch on error 


.WRITW 


• AREA J 


.»4.«BUFF 


,»Z5B. 


,BLK iWrite one block 


BCS 


at 






iBranch on error 


.SPFUN 


«AREAi 


i»^ .«372, 


»0 1 i«l 


iWrite a file Sap with Asynoh I/O 


.PRINT 


»DDNE 






iAnnounce that we're done 


.WAIT 


»a 






iWait for file Sap operation to finish 


.CLOSE 


»a 






iClose the file 


.EXIT 








ithen exit the proSram 


Moy 


■ »FERRi 


iRO 




iProcess errors here... 


BR 


5* 
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2$: 


Moy 

BR 


•LKERR >R0 
5$ 






3$: 


MOV 
BR 


•SPERR, RO 
5* 






4$: 


MOV 


•WERR.RO 






5$: 


■PRINT 
■ EXIT 






iPrint error inessase 
ithen exit program 


AREA: 


■ WORD 







iEMT ArSument blocK 


BLK: 


■ WORD 


O.O.OiO.O 






CT: 


■RflDSO 


/CT / 




iCassette- Deyice Descriptor 




■ NORD 


0.0 .0 




iNull filespeo 


BUFF: 


■ BLKW 


256, 




iOutput buffer 


DONE: 


■ASCIZ 


/All done 


!/ 


iMessaSe text,,, 


FERR: 


■ASCII 


/?. FETCH E 


rro r?/ 




LKERR: 


■ASCIZ 


/?. LOOKUP 


Er ro r?/ 




SPERR: 


■ASCIZ 


/?Special 


Funct ion 


Error?/ 


WERR: 


■ASCIZ 


/?Write Error?/ 






■ EVEN 










HSPC = ■ 






iHandler can load in here,,. 




■ END 


START 







2.89 .SPND/.RSUM (FB and XM Only) 

The .SPND/.RSUM requests control execution of a job's mainline code (the 
code that is not executing as a result of a completion routine). .SPND 
suspends the mainline and allows only completion routines (for I/O and 
mark time requests) to run. .RSUM from one of the completion routines 
resumes the mainline code. These functions enable a program to wait for a 
particular I/O or mark time request by suspending the mainline and having 
the selected event's completion routine issue a .RSUM. This differs from the 
.WAIT request, which suspends the mainline until all I/O operations on a 
specific channel have completed. 



Macro Calls: 



.SPND 
.RSUM 



Request Formats: 



(.SPND) 
(.RSUM) 



RO 
RO 



1 





2 






Notes: 



1. The monitor maintains a suspension counter for each job. This counter 
is decremented by .SPND and incremented by .RSUM. A job is sus- 
pended only if this counter is negative. Thus, if a .RSUM is issued 
before a .SPND, the latter request returns immediately. 

2. A program must issue an equal number of .SPND and .RSUM requests. 

3. A .RSUM request from the mainline code increments the suspension 
counter. 

4. A .SPND request from a completion routine decrements the suspension 
counter, but does not suspend the mainline. If a completion routine does 
a .SPND, the mainline continues until it also issues a .SPND, at which 
time it is suspended and requires two .RSUMs to proceed. 
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5. Since a .TWAIT is simulated in the monitor using suspend and resume, 
a .RSUM issued from a completion routine without a matching .SPND 
can cause the mainline to continue past a timed wait before the entire 
time interval has elapsed. 

6. A .SPND or .RSUM, like most other programmed requests, can be is- 
sued from within a user-written interrupt service routine if the 
.INTEN/.SYNCH sequence is followed. All notes referring to 
.SPND/.RSUM from a completion routine also apply to this case. 

Errors: 

None. 
Example: 



.TITLE 



SPND. MAC 



.SPND/.RSUM- This is an example in the use of the .SPND/.RSUM requests, 
The example is a simulation of a mainline ForeSround program which is 
currently suspended waitins for a messaSe from the Backsroundi but uhich 
needs to close a file (perhaps opened by a .ENTER ?) before abortinS 
from CTRL-C action, ft completion routine periodically inspects the CTRL-C 
status word and resumes the mainline if double CTRL-C is entered. 
NOTE: This example MUST be run as a FG Job under an FB monitor. 





.MCALL 


.SCCA, 


RCyDC.EXI 




.MCftLL 


.OSET. 


SPND.. RSUM 


START: 


.OSET 


SOELEM 


i«l 




.SCCA 


sMAREft 


.«SCCA 


1$: 


CALL 


CWATCH 






.RCWDC 


SMAREA 


.»MBUFF.«aO 



.Allocate another 0-Element 
.Inhibit ''C'C action by monitor 
.Start "watchdoS" completion rtne 
.sMESG iLooK for a message 

!No errors - there's always BG 
.Other processing here... 





■PRINT 


SSLEEP 




,SPND 






TST 


SCCA 




BNE 


CLOSE 




? < p roces s 


message 




BR 


li 


CWATCH: 


TST 


SCCA 




BEO 


MARK 


MESG: 


,RSUM 
RETURN 




MARK: 


.MRKT 
RETURN 


SCAREA 



.Announce we're SoinS to suspend 
.Suspend ta wait for message 
iWe'ue been , RSUMed . . . "C'C hit?? 
iBranoh if yes 
.otherwise assume messaSe came in, 



.Loop . 



iChecK if 'C'C entered... 
.Branch if no 

i Yes... wake up the mainline 
!then leaue completion code 
sCAREA i«TIME .SCWATCH i«l iSchedule to run aSain in 10 sec. 
ithen leave completion code 



CLOSE: 



.PRINT «ABORT 

i <DutPut file(5) closed here> 



.Announce we're aborting 
.proceed with "orderly" abort 



.EXIT 



OELEM: 


.BLKW 


7 


MBUFF: 


.BLKW 


ai . 


MAREA: 


.BLKW 


5 


CAREA: 


.BLKW 


a 


TIME: 


.WORD 


O.GOO. 


SCCA: 


.WORD 





ABORT: 


•ASCIZ 


/?! Ab 


SLEEP: 


.ASCIZ 


/! Mai 



iExit the pros ram 

.Extra 0-Element 
iMessaSe buffer 
iEMT Argument blocks 

.Time out in 10 seconds 
i "C*C Status word 



/?! Abort AcknowledSed.i.Closins Output File(s) 
/! Mainline Suspending !/ 



.END 



START 
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2.90 .SRESET 



The .SRESET (software reset) request: 

1. Cancels any messages sent by the job. 

2. Waits for all job I/O to complete, which includes waiting for all 
completion routines to run. 

3. Dismisses any device handlers that were brought into memory 
via .FETCH calls. Handlers loaded via the keyboard monitor 
LOAD command remain resident, as does the system device han- 
dler. 

4. Purges any currently open files. Files opened for output with .EN- 
TER are never made permanent. 

5. Reverts to using only 16(decimal) I/O channels. Any channels 
defined with .CDFN are discarded. A .CDFN must be reissued to 
open more than 16 channels after a .SRESET is performed. 

6. Clears the job's .SPND/.RSUM counter. 

7. Resets the I/O queue to one element. A .QSET request must be 
reissued to allocate extra queue elements. 

8. Cancels all outstanding .MRKT requests. 
Macro Call: .SRESET 

Errors: 



None. 
Example: 



.TITLE 



SRESET. MAC 



.SRESET - This is an example in the use of the .SRESET resuest. 

The example renames a file acoordinS to filespeos entered usinS the 

.CSISPC request . 





.MCALL 


.RENAME, .PRINT, .EXIT 




.MCALL 


.CSISPC, .FETCH, .SRESET 




ERRBYT 


= 52 


START: 


.CSISPC 


i<FILESP,«DEFEXT 




.FETCH 


»HANLOD,«FILESP 




BCS 


Z* 




MOU 


»FILESP,R2 




MOM 


«FILESP+aB ,R3 




MOM 


@R2 ,FILESP + 3B 




.REPT 


4 




MOM 


(R2)+,(R3)+ 




.ENDR 






.RENAME 


»AREA,«0,ttFILESP+3S 




OCC 


1$ 




DECB 


@«ERRBYT 




BEO 


3* 




MOM 


«ILLOP,RO 




BR 


5* 



iError byte location 

iUse .CSISPC to Set file specs 
iGet Handler from outspec 
sBranch if failed 
iR2 => Outspec 
iR3 = > Inspec 

!Cop'/ deuice spec to inspec 
iCopy outspec behind inspec 
if or .RENAME. , . 

iRename input file 
JQperation successful 
iMake error code -1,0 or +1 
iBranoh if File-Not-Found 
Sllleaal operation-set up msi 
iBranoh to report error 
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1$: 


.SRESET 
.EXIT 




Zt: 


Moy 


SNOHAN.RO 




BR 


5* 


3$: 


Moy 


»NOFIL.RO 


5$: 


.PRINT 






BR 


1» 


ftREPi: 


.BLKW 


5 


DEFEXT! 


.WORD 


lO lO (0 


NDFIL: 


.ASCIZ 


/?File not found?/ 


ILLOP: 


.ftSCIZ 


/?1 1 lesal Ope ration?/ 


NDHfiN: 


.flSCIZ 
.EVEN 


/?. FETCH Failed?/ 


FILESP: 


.BLKM 


39. 


HANLOD 


= . 






.END 


START 



iDismiss handlers 

iExi t p roSram 

iFetch failed-set up message 

iBranch to report error 

iFile not found-setup messaSe 

iPrint error messaSe 

iThen exit via .SRESET 

lEMT Argument blocK 

iNo default extensions 

iEr ro r messaSe text 



iCBISPC Input Area 
iHandlers can load here. 



2.91 .SYNCH (Device Handler and Interrupt Service Routine Only) 

This macro call enables your program to issue programmed requests from 
within an interrupt service routine. Code following the .SYNCH call runs 
at priority level as a completion routine in the issuing job's context. 
Programmed requests issued from interrupt routines are not supported by 
the system and should not be performed unless a .SYNCH is used. 
.SYNCH, like .INTEN, is not an EMT monitor request, but rather a sub- 
routine call to the monitor. 

Macro Call: .SYNCH area[,picj 

where: 



area 



pic 



is the address of a seven-word block that you must set aside 
for use by .SYNCH. This argument, area, represents a special 
seven-word block used by .SYNCH as a queue element. This 
is not the same as the regular area argument used by many 
other programmed requests. The user must not confuse the 
two; he should set up a unique seven-word block specifically 
for the .SYNCH request. The seven-word block appears as: 

Word 1 RT-11 maintains this word; its contents should not 
be altered by the user 

2 The current job's number. This must be set up by 
the user program. It can be obtained by a .GTJB 
call or from the I/O queue element in a device han- 
dler 

3 Unused 

4 Unused 

5 RO argument. When a successful return is made 
from .SYNCH, RO contains this argument 

6 Must be -1 

7 Must be 

is an optional argument that, if non-blank, causes the 
.SYNCH macro to produce position-independent code for use 
by device drivers 
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Note: 



.SYNCH assumes that the user has not pushed anything on the stack 
between the .INTEN and .SYNCH calls. This rule must be observed 
for proper operation. 



Errors: 



The monitor returns to the location immediately following the 
.SYNCH if the .SYNCH was rejected. The routine is still unable to 
issue programmed requests, and R4 and R5 are available for use. An 
error is returned if another .SYNCH that specified the same seven- 
word block is still pending. 

NOTE 

The monitor dismisses the interrupt without returning to the 
.SYNCH routine if one of the following conditions occur: 

1. You specified an illegal job number. 

2. The job number does not exist (for example, you specify 2, 
and there is no foreground job). 

3. The job is exited or terminated with an .EXIT pro- 
grammed request. 

You can find out if the block is in use by: 

1. Checking location Q.COMP (offset 14 octal). If this location con- 
tains a zero, the block is available. 

2. Performing a .SYNCH call. If the block is busy, an error return 
will be performed. 

Normal return is to the word after the error return. At this point, the 
routine is in user state and is thus allowed to issue programmed 
requests. RO contains the argument that was in word 5 of the block. 
RO and Rl are free for use without having to be saved. R4 and R5 are 
not free, and do not contain the same information they contained 
before the .SYNCH request. A long time can elapse before the pro- 
gram returns from a .SYNCH request since all interrupts must be 
serviced before the main program can continue. Exit from the routine 
should be done via an RTS PC. 



Example: 



.TITLE SYNCH. MAC 



.SYNCH - This is an example of the .SYNCH request. 

The example is a skeleton of a prodraw which could input data 

from the outside world by means of an in-line interrupt seruice routinei 

buffer it until a whole blooK's worth has been inputi then use 

a .WRITE request to store the data on an RT-11 device. 



Programmed Request Description and Examples 2-137 



.MCflLL 



.GTJB ..INTEN..WRITE..WAIT..SYNCH1.EXIT ..PRINT 



START! 



Moy 


SJ0B.R5 


.GTJB 


«flREfl.R5 


MOV 


(R5) ,SYNBLK + 2 



INTRPT: 



.INTEN 





.SYNCH 


SSYNBLK 






BR 


SYNFAIL 






1 

.WAIT 


«1 






BCS 


WRFftIL 






WRITE 


8AREA.«1 


.0BUFF,«25G. 




INC 


BLK 






RETURN 






SYNBLK: 


.WORD 









.WORD 









.WORD 









.WORD 









.WORD 


5 






.WORD 


-1 lO 




SYNFfllL: 









WRFAILs MOy 


SWERR.RO 


ERRM: 


.PRINT 
.EXIT 




BLK: 


.WORD 





AREA: 


.BLKW 


5 


JOB: 


.BLKW 


8. 


OBUFF 


.WORD 





IBUFF 


.WORD 





BUFFI 


.BLKW 


Z5G. 


BUFF2 


.BLKW 


25S. 


WERR: 


.ASCIZ 


/?Write Error?/ 


SYNERF 


(! .ASCIZ 
.EVEN 


/?SYNCH Failed?/ 



Results of .GTJB So here 
Get Job number (either FG or BG) 
Store Job number in .SYNCH blocK 
Here we open an RT-11 output 
device 1 then initiate input from 
a "foreisn" deuioet interrupts to 
be handled by our in-line interrupt 
seruioe routine.... 
INTERRUPT SERVICE ROUTINE 
Notify RT-11 and drop to priority 5 
Prooess interrupt and buffer input 
Time to write a buffer - switch 
buffers (should be double buffered 
so that interrupt processing can 
continue durinS write operation). 
Do a .SYNCH so we can use a .WRITE 
Return here if a .SYNCH blocK in use 
Return here if oKay... 
See if error on last write 
Branch if there was 
.BLK 

Queue a write to store the data 
and bump the blocK number. 
Re-enable interrupts and leaue 

.SYNCH blocK 

Job number soes here 

Next two words reserved 

RO contains 5 on successful .SYNCH 
Re'iuired values for the Monitor 

.SYNCH failed. , . 

This can be a problem if the 

next interrupt came in before the 

buffer was written out! 

RO^ error messaSe text 
Output the error message 
then exit. 

BlocK number to write 

EMT A rsument b 1 ooK 

Area for .GTJB data 

Pointer to current output buffer 

Pointer to current input buffer 

Buffer 1 

Buf f e r 2 



END 



START 



2.92 .TIMID (Device Handler Only) 

The .TIMIO macro issues the device time-out call in the handler I/O initia- 
tion section. This request schedules a completion routine to run after the 
specified time interval has elapsed. The completion routine runs in the 
context of the job indicated in the timer block. In XM systems, the comple- 
tion routine executes with kernel mapping, since it is still a part of the 
interrupt service routine. (See the RT-11 Software Support Manual for 
more information about interrupt service routines and the XM monitor.) As 
usual with completion routines, RO and Rl are available for use. When the 
completion routine is entered, RO contains the sequence number of the 
request that timed out. 
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Macro Call: .TIMIO tbk,hi,lo 
where: 

tbk is the address of the timer block, a seven- word pseudo timer 
queue element. (The timer block format is shown in Table 2-1 
under the .CTIMIO request.) You must set up the address of 
the completion routine in the seventh word of the timer block 
in a position-independent manner 

is the high-order word of a two-word time interval 

is the low-order word of a two-word time interval 



hi 
lo 
Example: 



.TITLE TIMIO. MAC 



i TIMIO. MAC - This is an example of a siniplei RT-11 deuioe driueri 
i to illustrate the use of the .TIMID/. CTIMIO re'iuests. The timeout 
1 CQWPletion routine will be entered if a charaoter hasn't been 
i suocessfully transmitted in 1/10 seo (approx. 110 baud). In this 
i example the completion routine taKes no explicit action! the fact 
i that the timeout occurred is enough to be considered a "hard" error. 



.MCflLL 



. DRBEGi.DRflST .. DRFIN .. DREND ,. OELDF .. TIMIO .. CTIMIO 



. IIF NDF MMG$Ti MMG$T = 
I IIF NDF ERLfG. ERL»G = 
,IIF NDF TIM*IT. TIM*IT=0 



iDefine these in case not 
iassembled uith SYSCND.MflC 



,IIF NDF SP$VEC. SP*yEC=30a 

, IIF NDF BPfCSR. SP*CSR= 170503 

,IIF NDF SP*PRI. SP$PRI=a 



iDefine default Meotor 
iDefine default CSR addr 
iDefine default deuice priority 



lOERR = 1 iHard I/O error bit definition 



SPSTS = 20000 



iDeuice Status = Write only 



SPSIZ = iOeuice Size = (Char deuioe) 



TIME = S 
COD = 377 



iTimeout interval = 1/10 sec 
iDeuice i.d. code 



SPRET: 



.OELDF 
.DRBEG 

Moy 

flSL 

BCC 

BEO 

MOM 

ADD 

MOO 

.TIMIO 

BIS 

RETURN 



SP.SP*yEC > SPSIZ , SPSTS 

SPCOE.Ra 

0$WCNT(Ra) 

SPERR 

SPDUN 

PCiR5 

SSPTOUT-. ,R5 

R5 >TBLK + 14 

TBLK lOiTIME 

«100 >e«SP*CSR 



iUse .OELDF to define 0-Elem offsets 

iBeiin driver code uith .DRBEG 

iRfl => Current 0-Element 

iMaKe word count byte count 

iA read from a write/only deuice? 

iZero word count. ..Just exit 

iCalculate PIC address 

icompletion routine 

iMoue it to argument blocK 

iSchedule a marKtime 

iEnable DL-11 interrupt 

iReturn to monitor 



; INTERRUPT SERVICE ROUTINE 



.DRAST 


SP.SPtPRI 


MOO 


SPCOE.Ra 


TST 


esSPtCSR 


BMI 


SPRET 


TSTB 


esSPtCSR 


BPL 


SPRET 


.CTIMIO 


TBLK 


BCS 


SPERR 


MOOB 


BO«BUFF(Ra) .§«SP$CSR + Z 


INC 


0*BUFF(R4) 


INC 


0*NCNT(R4) 



iUse .DRAST to define Int Sue Sect. 

iRa => 0-Element 

iE r ro r? 

i Yes . . t ' han d ' until ready 

ils device ready? 

iNo...3o wait 'till it is 

iCancel completion routine 

iToo late - it timed out! 

iXfer byte from buffer to DL-U 

iBump the buffer pointer 

iand the word count (it's nesatiue!) 
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BEO 


SPDUN 




5R 


SPRET 


SPTOUT: 


RETURN 


• 


SPERR: 


BIS 


«IOERR.eO$CSW(Ra) 


SPDUN: 


.DRFIN 


SP 


TBLK: 


.WORD 


0(TIME.0.0.177000 + CQD 




.DREND 


SP 




.END 





iBranoh if done 

iGo uait 'till char Kmitted 

iTimeout completion routine 
iln this eKamplei it does nothing, 
iln real life it may want to try 
ito taKe some correotive action.. 

iSet error bit in CSW 

iUse .DRFIN to return to Monitor 

i. TIMID argument blooK 

iUse .DREND to end code 



2.93 .TLOCK 



The .TLOCK (test lock) request is used in an FB environment to attempt to 
gain ownership of the USR. It is similar to .LOCK in that, if successful, the 
user job returns with the USR in memory (it is identical to .LOCK in the SJ 
monitor). However, if a job attempts to .LOCK the USR while another job is 
using it, the requesting job is suspended until the USR is free. With 
.TLOCK, if the USR is not available, control returns immediately with the 
C bit set to indicate the .LOCK request failed. 

Macro Call: .TLOCK 

Request Format: 

RO = 







Errors: 

Code Explanation 

USR is already in use by another job. 
Example: 

.TITLE TLOCK. MAC 



i .TLOCK - This is an example in the use of the .TLOCK request. 

i In this example! the user prosram needs the USR for a sub-Job it is 

i exeoutins. If it fails to Set the USR it "suspends" that sub-Job and 

i runs another sub-Job (that perhaps doesn't need the USR for execution), 

1 This type of procedure is useful to schedule seueral sub-Jobs uithin 

i a single bacKSround or foresround proSram. 



.MCALL 



.TLOCK I. LOOK UP.. UNLOCK ., EXIT .. PRINT 



START: 



.TLOCK 




BCS 


SUSPND 


.LOOKUP 


«AREA.«a.»FILE 


BCS 


LKERR 


1 

•PRINT 


SJIMSG 


.UNLOCK 




TSTB 


JZSW 


BNE 


1* 


CALL 


J0B2 


.EXIT 





iBeSin Mainline proSram 

iTry to Set the USR for 1st "Job" 

iFai led ... b ranch to "suspend" 1st Job 

iSucoeeded . > . p roceed uith 1st Job 

iBranch if error on LOOKUP 

ilst Job inuolues file processin 9 . . . do it! 

iTell user we executed... 

ilst Job finished ... release USR 

iCheoK if ue ran Job «Z while USR busy 

lYup - we did 

iNope - do it now 
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SUSPND: 



TSTB 

BNE 

JSR 

INC 

BR 



J2SW 

START 

PC.JOBZ 

J2SW 

START 



i "Suspend" current "Job" 

iDid ue already run Job «2 

!Ye5 - don't do it aSain 

i"Run" other "Job" 

iSet Buitch that says ue ran Job «2 

iWhen it's finished) try 1st Job aSain 



AREA: 
FILE: 



LKERR: 

LKMSG! 
JIMSG: 
J2MSG: 
J2SW! 



.BLKW 

.RAD50 

.RAD50 

.RAD50 

.PRINT 

.EXIT 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.BYTE 

.EVEN 



5 

/DK/ 

/OUFILE/ 

/TMP/ 

SLKMSG 

/?File Not Found?/ 
/Job »1 Exeouted/ 
/Job »2 Executed/ 




iEMT argument blooK 
iFi le spec for Job »1 



iError on .LOOKUP - Report it! 



!Suitch to control Job *Z execution 



J0B2: 



.PRINT 
RTS 



»J2MSG 
PC 



i2nd "Job" - Doesn't need USR 
iReturn uhen done 



.END 



START 



2.94 .TRPSET 



.TRPSET allows the user job to intercept traps to 4 and 10 instead of having 
the job aborted with a ?MON-F-Trap to 4 or ?MON-F-Trap to 10 message. 
If .TRPSET is in effect when an error trap occurs, the user-specified routine 
is entered. The status of the carry bit on entry to the routine determines 
which trap occurred: carry bit clear indicates a trap to 4; carry bit set 
indicates a trap to 10. The user routine should exit with an RTI instruction. 
Traps to 4 can also be caused by user stack overflow on some processors 
(check your processor handbook). These traps are not intercepted by the 
.TRPSET request, but they do cause job abort and a printout of the message 
?MON-FStack overflow in the SJ monitor or ?MON-F-Trap to 4 in the FB 
and XM monitors (see the RT—11 System Message Manual). 

Macro Call: .TRPSET area,addr 



where: 



area is the address of a two-word EMT argument block 

addr is the address of the user's trap routine. If an address of is 
specified, trap interception is disabled 



Request Format: 



RO 



area: 



ij„ 

CIU.U.J. 



Notes: 



Reissue a .TRPSET request whenever an error trap occurs and the user 
routine is entered. The monitor disables user trap interception prior to 
entering the user trap routine. Thus, if a trap should occur from within 
the user's trap routine, an error message is generated and the job is 
aborted. The last operation the user routine should perform before an 
RTI is to reissue the .TRPSET request. 
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2. In the XM monitor, traps dispatched to a user program by .TRPSET 
execute in user mode. They appear as interrupts of the user program by 
a synchronous trap operation. Programs that intercept error traps by 
trying to steal the trap vectors must be carefully designed to handle two 
cases accurately: programs that are virtual jobs and programs that are 
privileged jobs. 

If the program is a virtual job, the stolen vector is in user virtual space 
that is not mapped to kernel vector space. The proper method is to use 
.TRPSET; otherwise interception attempts fail and the monitor contin- 
ues to handle traps to 4 and 10. 

If the program is a privileged job, it is mapped to the kernel vector 
page. The user can steal the error trap vectors from the monitor, but 
the benefits of doing so must be carefully evaluated in each case. Trap 
routines run in the mapping mode specified by bits 14 and 15 of the trap 
vector PS word. With both bits set to 0, kernel mode is set. However, 
kernel mapping is not always equivalent to user mapping, particularly 
when extended memory is being used. With both bits 14 and 15 of the 
PS set to 1, user mode is set, and the trap routine executes in user 
mapping. 



Errors: 

None. 
Example: 



.TITLE TRPSET. MAC 



.TRPSET - This is an example in the use of the .TRPSET request. 
In this exariiple a user trap routine is sett then deliberate 
traps to fl & 10 are caused (not uery practical but it demonstrates 
that .TRPSET really worKs!). 





.MCALL 


.TRPSET, .EXIT 




Diyz = B7 




START: 








.TRPSET 


wAREA.ttTRPLOC 




Diyz 






TST 


littlSSSSB 




.EXIT 




TRPLOC: 








BCS 


1* 




.PRINT 


«TRPa 




BR 


2t 


1$: 


.PRINT 


ttTRPlO 




.TRPSET 


«AREA.«TRPLOC 


2$: 


RTI 




AREA: 


.NORD 


0.0 


TRPa; 


.ASCIZ 


/?Trap to ai/ 


TRPIO: 


.ASCIZ 


/?Trap to 10?/ 



iDiuide by zero - illeSal instruction 

iBeSin example 

iSet UP a trap routine to handle traps 

ito a & 10. . . 

illleSal instruction - Trap to 10 

iAddress non-existent memory - Trap to 4 

lExit program 

iTrap routine 

!C bi t set = TRAP 10 

iReport Trap to 4 

jBranch to reset trap routine 

iRepo rt t rap to 10 

iReset trap routine address 

iReturn to offending code 

iEMT a rsument b 1 ocK 
lError messages... 



.END 



START 
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2.95 .TTYIN/.TTINR 



The requests .TTYIN and .TTINR transfer a character from the console 
terminal to the user program. The character thus obtained appears right- 
justified (even byte) in RO. The user can cause the characters to be returned 
in RO only, or in RO and other locations. 

The expansion of .TTYIN is: 

EMT 340 
BCS .-2 

The expansion of .TTINR is: 

EMT 340 

If no characters or lines are available when an EMT 340 is executed, return 
is made with the carry bit set. The implication of these calls is that .TTYIN 
causes a tight loop waiting for a character/line to appear, while the user 
can either wait or continue processing using .TTINR. 

If the carry bit is set when execution of the .TTINR request is completed, it 
indicates that no character was available; the user has not yet typed a valid 
line. Under the FB or XM monitor and under an SJ monitor with multi ter- 
minal support, .TTINR does not return the carry bit set unless bit 6 of the 
job status word (JSW) was on when the request was issued. 

There are two modes of doing console terminal input. The choice is gov- 
erned by bit 12 of the job status word. If bit 12 is 0, normal I/O is performed. 
In this mode, the following conditions apply: 

1. The monitor echoes all characters typed. 

2. CTRL/U and the DELETE key perform line deletion and charac- 
ter deletion, respectively. 

3. A carriage return, line feed, CTRL/Z, or CTRL/C must be struck 
before characters on the current line are available to the pro- 
gram. When one of these is typed, characters on the line typed are 
passed one by one to the user program. 

If bit 12 is 1, the console is in special mode. The effects are: 

1. The monitor does not echo characters typed except for CTRL/C 
and CTRL/0. 

O riTTDT /TT ^-^A ^-^ — T\T?J TTTIT? l,„,r J„ i- „ f ^^ „ -'^1 *■ •+- '^ 

3. Characters are immediately available to the program. 

In special mode, the user program must echo the characters received. How- 
ever, CTRL/C and CTRL/0 are acted on by the monitor in the usual way. 
Bit 12 in the JSW must be set by the user program. This bit is cleared when 
the program terminates. 
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Regardless of the setting of bit 12, when a carriage return is entered, both 
carriage return and line feed characters are passed to the program; if bit 12 
is 0, these characters will be echoed. 

Lowercase conversion is determined by the setting of bit 14 in the JSW. If 
bit 14 is 0, lowercase characters are converted to uppercase before being 
echoed (if bit 12 is 0) and passed to a program; if bit 14 is 1, lowercase 
characters are echoed (if bit 12 is 0) and passed as received. Bit 14 is 
cleared when the program terminates. 

CTRL/F and CTRL/B (and CTRL/X in system job monitors) are not affected 
by the setting of bit 12. The monitor always acts on these characters (unless 
the SET TT NOFB command is issued). 

CTRL/S and CTRL/Q are intercepted by the monitor (unless, under the FB 
or XM monitor, the SET TT NOP AGE command is issued). 

Under the FB or XM monitor, if a terminal input request is made and no 
character is available, job execution is blocked until a character is ready. 
This is true for both .TTYIN and .TTINR, and for both normal and special 
modes. If a program requires execution to continue and the carry bit to be 
returned, it must set bit 6 of the Job Status Word before the .TTINR re- 
quest. Bit 6 is cleared when a program terminates. 

If the single-line editor has been enabled by the commands SET SL ON and 
SET SL TTYIN, and if bits 4 and 12 of the JSW are 0, input from a .TTYIN 
or .TTINR request will be edited by SL. If either bit 4 or bit 12 is set, SL 
will not edit input. If SL is editing input, the state of bit 6 (inhibit TT wait) 
is ignored and a .TTINR request will not return until an edited line is 
available. 

NOTE 

The .TTYIN request does not get characters from indirect 
files. If this function is desired, the .GTLIN request must be 
used. 

Macro Calls: .TTYIN char 
.TTINR 

where: 

char is the location where the character in RO is to be stored. If 
char is specified, the character is in both RO and the address 
represented by char. If char is not specified, the character is 
inRO 

Errors: 

Code Explanation 

No characters available in ring buffer. 

Example: 

Refer to the example following the description of 
.TTYOUT/.TTOUTR. 
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2.96 .TTYOUT/.TTOUTR 

\ The requests .TTYOUT and .TTOUTR cause a character to be transmitted 

to the console terminal. The difference between the two requests, as in the 
.TTYIN/.TTINR requests, is that if there is no room for the character in the 
monitor's buffer, the .TTYOUT request waits for room before proceeding, 
while the .TTOUTR does not wait for room and the character is not output. 

If the carry bit is set when execution of the .TTOUTR request is completed, 
it indicates that there is no room in the buffer and that no character was 
output. Under the FB or XM monitor, .TTOUTR normally does not return 
the carry bit set. Instead, the job is blocked until room is available in the 
output buffer. If a job requires execution to continue and the carry bit to be 
returned, it must turn on bit 6 of the Job Status Word before issuing the 
request. 

The .TTINR and .TTOUTR requests have been supplied to help those users 
who want to continue rather than suspend program execution until a con- 
\ sole operation is complete. With these modes of I/O, if a no-character or no- 

room condition occurs, the user program can continue processing and try 
the operation again at a later time. 

NOTE 

If a foreground job leaves bit 6 set in the Job Status Word, 
any further foreground .TTYIN or .TTYOUT requests cause 
the system to lock out the background until a character is 
j available. Note also that each job in the foreground/back- 

ground environment has its own Job Status Word, and there- 
fore can be in different terminal modes independently of the 
other job. 

Macro Call: .TTYOUT char 
.TTOUTR 

where: 

char is the location containing the character to be loaded in RO and 
printed. If not specified, the character in RO is printed. Upon 
return from the request, RO still contains the character 

Errors: 

Code Explanation 

Output ring buffer full. 
Example: 

.TITLE TTYIN. MAC 

^ 

.TTYIN / .TTYOUT - This is an example in the use of the .TTYIN 
& .TTYOUT requests. The example accepts a line of input from the 
console Keyboard) then echoes it on the terminal. Usini .TTYIN & 
•TTYOUT requests illustrate Synchronous terminal I/Oi i.e.) the 
Monitor retains control (the Job is blooKed) until the requests 
are satisfied. 



Programmed Request Description and Examples 2-145 



.MCfiLL 



.TTYINi.TTYOUT 



STftRT: 


Moy 


• BUFFER, Rl 




CLR 


R2 


INLODP: 


.TTYIN 


(Rl) + 




INC 


R2 




CMPB 


»1Z,R0 




BNE 


INLODP 




Moy 


• BUFFER, Rl 


DUTLODP: 


.TTYOUT 


(Rl) + 




DEC 


RZ 




BEQ 


START 




BR 


DUTLODP 


BUFFER: 


.BLKW 


sa. 




.END 


START 




.TITLE 


TTINR.MAC 



iRl => Character buffer 

iClear character count 

iRead char into buffer 

iBump count 

iWas last char a LF ? 

iNo...det next character 

iYes.. .point Rl to besinnin9 of buffer 

iPrint a charaote r 

iDec rease count .. . 

iDone if count = 

iLoop to print another character 

iCha racte r buffer... 



.TTINR / .TTOUTR - This is an example in the use of the .TTINR & 
.TTOUTR requests. Like TTYIN. MAC, this example accepts lines of 
input from the console Keyboard, then echoes it on the terminal. 
But rather than waiting for the user to type somethinS at 'INLODP' 
or wait for the output buffer to haue available space at 'OUTLOOP' 
the routine has been receded usins .TTINR and .TTOUTR to allow 
other processing to be carried out if a wait condition is reached. 





.MCALL 


. TTYIN, .TT 




.MCALL 


. TTINR, .TT 




jsw = aa 




START! 


Moy 


•BUFFER, Rl 




CLR 


R2 




BIS 


»100,@«JSW 


INLOOPi 


.TTINR 






BCS 


NOCHAR 


CHRIN: 


MOVB 


R0,(R1)+ 




INC 


R2 




CMPB 


R0,^12 




BNE 


INLODP 




Moy 


• BUFFER, Rl 


OUTLOOP: 


MOVB 
.TTOUTR 


(Rl) ,R0 




BCS 


NOROOM 


CHROUT: 


DEC 


R2 




BEO 


START 




INC 


Rl 




BR 


OUTLOOP 


NOCHAR: 


.TTINR 






BCC 


CHRIN 



NOROOM: 



BR 



nuvD 

.TTOUTR 

BCC 



NOCHAR 



f.n L t ,itu 



CHROUT 





BIC 


«100,@«JSW 




.TTYOUT 


(Rl) 




BIS 


»100,@»JSW 




BR 


CHROUT 


BUFFER! 


.BLKW 


S4. 




.END 


START 



Location of Job Status Word in SYSCOM 

Point Rl to buffer 

Clear character count 

Set bit •E in JSW so . TTINR/ .TTOUTR will 

return C bit set if no char/no room... 

Get char from terminal 

None auai lab le 

Put char in buffer 

Ino rease count 

Was last char = LF? 

No ... Set next char 

Yes. ..point Rl to beSinninS of buffer 

Put char in RO 

Try to print it 

Branch if no room in output buffer 

Deo rease count 

Done if count=0 

Bump buffer pointer 

then branch to print next char 

Comes here if no char auail 
try to a9ain to Set one 
There's one auail this time! 

Do other processins 

Try aSain 

Comes here if no room in buffer 

Put char- in R 

Try to print it aSain 

Successful ! 

Code to be executed while waiting 

Now ue must hans to wait... 
Clear bit «S in JSW 
Use .TTYOUT to wait for room 
Finally successful - reset bit «B 
then return to output loop 

Buf f e r 
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2.97 .TWAIT (SYSGEN Option for SJ) 

The .TWAIT request suspends the user's job for an indicated length of time. 
.TWAIT requires a queue element and thus should be considered when the 
.QSET request is issued. 



Macro Call: 
where: 



.TWAIT area,time 



area is the address of a two- word EMT argument block 

time is a pointer to two words of time (high order first, low order 
second), expressed in ticks 

Request Format: 

RO -» area: 



24 







time 



Notes: 



1. Since a .TWAIT is simulated in the monitor using suspend and resume, 
a .RSUM issued from a completion routine without a matching .SPND 
can cause the mainstream to continue past a timed wait before the 
entire time interval has elapsed. In addition, a .TWAIT issued within a 
completion routine is ignored by the monitor, since it would block the 
job from ever running again. 

2. The unit of time for this request is clock ticks, which can be 50 Hz or 60 
Hz, depending on the local power supply, if your system has a line 
frequency clock. This must be kept in mind when the time interval is 
specified. 

Errors: 

Code Explanation 

No queue element was available. 
Example: 

.TITLE TWftlT.MAC 



•TWftlT - This is an example in the use of the .TWflIT request. 
.TWftIT is useful in applications where a prosram must be only 
activated periodically. This example will 'waKe up' every five seconds 
to perform a simulated "task's and then 'sleep' adain. (For example 
purposes this cycle will be repeated for a maximuw of about 35 see). 



START: 
1$: 



.MCflLL 

CALL 

.TWAIT 

BCS 

CALL 

DEC 

BNE 

.PRINT 

.EXIT 



.TWAIT i.OSET ..EX IT (.PRINT 



TASK 

»DAREA.»TIME 

NQO 

TASK 

COUNT 

1* 

«BYE 



iPe rf rm tasK . . . 

iGo to sleep for 5 seconds 

iBranoh if no sueue element 

iPe rf rm tasK aSain 

iBump counter - example Sood for 35 sec 

iBranoh if time's not up 

JSay we're thru 

iExi t p rosram 
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TASK: 










iPeriodio tasK simulated here 




INC 


TCNT 






iBump a oDunt e r 




BIT 


»1 .TCNT 






i 1 5 it odd? 




BEO 


1$ 






iBranoh i f not 




.PRINT 


STICK 






iDdd oounter prints "ticK..." 




RETURN 








iRet u rn to oal le r 


1»: 


.PRINT 
RETURN 


«TOCK 






iEuen counter prints "tooK" 
iReturn to caller 


NOO! 


.PRINT 
.EXIT 


«OERR 






iPrint error messase 
iEKi t p rosram 


flREfl: 


.WORD 


0.0 






iEMT Arsument blocK 


TIME: 


.WORD 


O.GO.»5 


. 




iBO tioKs/seo ♦ 5 seconds 


COUNT: 


.WORD 


7 






iMaximum o/cles for example 


TCNT: 


.WORD 









iTi cK It ocK count 


TICK: 


.ASCII 


/Tick. . 


./<200> 




iMessaSe text 


TOCK: 


.flSCIZ 


/Took/ 








BYE: 


.ftSCIH 


/Exampl 


e Conoluded/ 




OERR: 


.ASCIZ 


/?No 0-Element 


Auai 1 


able?/ 




.END 


START 









2.98 .UNLOCK 

See .LOCK/.UNLOCK (Section 2.45). 

2.99 .UNMAP (XM Only) 

The .UNMAP request unmaps a window and flags that portion of the pro- 
gram's virtual address space as being inaccessible. When an unmap opera- 
tion is performed for a virtual job, attempts to access the unmapped address 
space cause a memory management fault. For a privileged job, the default 
(kernel) mapping is restored when a window is unmapped. 

Macro Call: .UNMAP area,addr 

where: 

area is the address of a two-word argument block 

addr is the address of the window control block that describes the 
window to be unmapped 

Request Format: 

RO -^ area: 



36 



addr 



Errors: 






Exi^lanstion 



3 An illegal window identifier was specified. 
5 The specified window was not already mapped. 
Example: 

Refer to the example following the description of .CRAW. 
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2.100 .UNPROTECT 

See .PROTECT/.UNPROTECT (Section 2.64). 



2.101 .WAIT 



The .WAIT request suspends program execution until all input/output re- 
quests on the specified channel are completed. The .WAIT request, com- 
bined with the .READ/. WRITE requests, makes double buffering a simple 
process. 

.WAIT also conveys information through its error returns. An error is re- 
turned if either the channel is not open or the last I/O operation resulted in 
a hardware error. 

If an asynchronous operation on a channel results in end-of-file, the follow- 
ing .WAIT programmed request will not detect it. The .WAIT request de- 
tects only hard error conditions. A subsequent operation on that channel 
will detect end-of-file and will return to the user immediately with the 
carry bit set and the end-of-file code in byte 52. Under these conditions, the 
subsequent operation is not initiated. 

In an FB system, executing a .WAIT when I/O is pending causes that job to 
be suspended and another job to run, if possible. 

Macro Call: .WAIT chan 

Request Format: 

RO = 

Errors: 

Code Explanation 

Channel specified is not open. 

1 Hardware error occurred on the previous I/O operation on 
this channel. 

Example: 







chan 



.TITLE WAIT. MAC 



.WAIT - This is an example in the use of the .WAIT request. The 
example demonstrates asynchronous I/O where a mainline prosram 
initiates input via .READ requests, does some other prooessinSi 
fflaKes sure input has completed via the .WAIT request, then out- 
puts the blocK Just read. Another .WAIT is issued before the next 
read is issued to make sure the previous write has finished. This 
example is a sinsle file copy prosram. utilizing .CSIGEN to input 
the file specs, load the required handlers and open the files. 



.MCALL 


.READ ..WRITE. 


CLOSE, 


.PRINT 


.MCALL 


.CSIGENi.EXIT 


..WAIT, 


.SRESET 


ERRBYT 


= 52 




iEr ro 



iError Byte location in SYSCDM 
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STftRT: 
1$: 



2*: 



.ENABL 

.CSIGEN 

MOU 

■ READ 

BCS 

? 

BIT 

BNE 

.PRINT 

! 

.WftIT 

BCS 

.WRITE 

BCS 



LSB 

BDSPflCE ittDEFEXT 

sftREft tR5 

R5,«3 

B» 

»1 iIOBLK 

2* 

»MESSG 

«3 
5$ 

R5 .«0 
3$ 



iEnable local symbol blooK 

iUse CSIGEN to Set handlersi files 

iR5 => EMT flrSument list 

iRead a block... 

iBranch on error 

iThen simulate 
isome other 
imeaninsfult?) process... 

iDid read finish OK? 

iBranch if not 

iNou write the blocK Just read 

iBranch on error 

iCould do some more prooessini here. 



3$: 
4$: 



5«: 
6$: 



flREft: : 
lOBLK: 



BUFF: 

DEFEXT 

DONE: 

MESSG 

WRERR 

RDERR 

EOF: 

DSPflCE 



INC 

.WAIT 

BCC 

MOU 

.PRINT 

.EXIT 

MOM 

BR 

TSTB 

BNE 

.PRINT 

.CLOSE 

.BRESET 

.EXIT 

.WORD 

.WORD 

.WORD 

.WORD 

.WORD 

.BLKW 

.WORD 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.BYTE 

.EVEN 



lOBLK 

1* 
ttWRERR .RO 



WRDERR.RO 

at 

e»ERRBYT 
5* 

SDONE 
«0 



Bump block « for next read 
Wait for write to finish 
Branch if successful 
RO => Write error msJ 
Report error 
then exit pro 9ram 
RO => Read error ms S 
Branch to report error 
Read error.. .EOF? 
B ranch if not 

Yes ... announce completion 
Make output file permanent 
Dismiss fetched handlers 
then exit program 

!EMT Area block 

iBlock » I 

BUFF iBuffer addr & word count 

25B. ialready fixed in block... 



25B. iI/0 buf f e r 

OiOiOiO iNo default extensions for CSIGEN 

/I-O Transfer Complete/ jMessaSes... 

<15><12>/< Simulating Mainline Processing >/ 

/?Write Erro r?/ 

/?Read Erro r?/ 

iEDF flas 

iHandlers ma'/ be loaded startins here 



.END 



START 



2.102 .WDBBK {XM Only) 



The .WDBBK macro defines symbols for the window definition block and 
reserves space for it. Information provided to the arguments of this macro 
permits the creation and mapping of a window through the use of the 
.CRAW request. Note that .WDBBK automatically invokes .WDBDF. 

Macro Call: .WDBBK wnapr,wnsiz[,wnrid,wnoff,wnlen,wnsts] 

where: 

wnapr is the number of the Active Page Register set that includes 
the window's base address. A window must start on a 4K- 
word boundary. The valid range of values is from through 

7 

wnsiz is the size of this window (expressed in 3 2- word units) 

wnrid is the identification for the region to which this window 
maps. This argument is optional; supply it if you need to 
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map this window. Use the value of R.GID from the region 
definition block for this argument after you create the re- 
gion to which this window must map 

wnoff is the offset into the region at which to start mapping this 
window (expressed in 32-word units). This argument is op- 
tional; supply it if you need to map this window. The default 
is 0, which means that the window starts mapping at the 
region's base address 

wnlen is the amount of this window to map (expressed in 32-word 
units). This argument is optional; supply it if you need to 
map this window. The default value is 0, which maps as 
much of the window as possible 

wnsts is the window status word. This argument is optional; sup- 
ply it if you need to map this window when you issue the 
.CRAW request. Set bit 8, called WS.MAP, to cause .CRAW 
to perform an implied mapping operation 

Example: 

See Chapter 4 of the RT-11 Software Support Manual for an example 
that uses the .WDBBK macro and a detailed description of the ex- 
tended memory feature. 



2.103 .WDBDF (XM Only) 



The .WDBDF macro defines the symbolic offset names for the window defi- 
nition block and the names for the window status word bit patterns. In 
addition, this macro also defines the length of the window definition block 
by setting up the following symbol: 

W.NLGH = 16 

The .WDBDF macro does not reserve any space for the window definition 
block (see .WDBBK). 

Macro Call: .WDBDF 

The .WDBDF macro expands as follows: 



W.NID 


= 





W.NAPR 


= 


1 


W.NBAS 


= 


2 


W.NSIZ 


= 


4 


W.NRID 


= 


6 


W.NOFF 


= 


10 


W.NLEN 


= 


12 


W.NSTS 


= 


14 


W.NLGH 


= 


16 


WS.CRW 


= 


100000 


WS.UNM 


= 


40000 


WS.ELW 


= 


20000 


WS.MAP 


= 


400 
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2.104 .WRITE/.WRITC/.WRITW 



Write operations for the three modes of RT-11 I/O are done using the 
.WRITE, .WRITC, and .WRITW programmed requests. 

Note that in the case of .WRITE and .WRITC, additional queue elements 
should be allocated for buffered I/O operations (see .QSET programmed 
request). 

Under an FB monitor with the system job feature, .WRITE/C/W requests 
may be used to send messages to other jobs in the system. 

.WRITE 

The .WRITE request transfers a specified number of words from memory to 
the specified channel. Control returns to your program immediately after 
the request is queued. 

Macro Call: .WRITE area,chan,buf,wcnt,blk 

where: 

area is the address of a five-word EMT argument block 

chan is a channel number in the range to 376(octal) 

buf is the address of the memory buffer to be used for output 

went is the number of words to be written 

blk is the block number to be written. For a file-structured 
.LOOKUP or .ENTER, the block number is relative to the 
start of the file. For a non-file-structured .LOOKUP or .EN- 
TER, the block number is the absolute block number on the 
device. The user program should normally update hlk before 
it is used again. Some devices, such as LP, may assign the blk 
argument special meaning. For example, if blk = 0, LP: is- 
sues a form feed 

Request Format: 

RO -> area: 



11 chan 



blk 



buf 



went 



When any .WRITE, .WRITC, or .WRITW programmed re- 
quest is returned, RO contains the number of words requested 
if the write is to a sequential-access device (for example, 
magtape). If the write is to a random-access device (disk or 
DECtape), RO contains the number of words that will be writ- 
ten (.WRITE or .WRITC) or have been written (.WRITW). If a 
request is made to write past the end-of-file on a random- 
access device, the word count is shortened and an error is 
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returned. The shortened word count is returned in RO. If a 
write goes past EOT on magtape, an error is returned and 
RO = 0. Note that the write is done and a completion routine, 
if specified, is entered, unless the request cannot be partially 
filled (shortened word count = 0). 

Errors: 

Code Explanation 

Attempted to write past end-of-file. 

1 Hardware error. 

2 Channel was not opened. 
Example: 

Refer to the example following .READ. 

.WRITC 

The .WRITC request transfers a specified number of words from memory to 
a specified channel. Control returns to the user program immediately after 
the request is queued. Execution of the user program continues until the 
.WRITC is complete, then control passes to the routine specified in the 
request. When an RTS PC is encountered in the completion routine, control 
returns to the user program. 

Macro Call: .WRITC area,chan,buf,wcnt,crtn,blk 

where: 

area is the address of a five-word EMT argument block 

chan is a channel number in the range to 376(octal) 

buf is the address of the memory buffer to be used for output 

went is the number of words to be written 

crtn is the address of the completion routine to be entered 

blk is the block number to be written. For a file-structured 
.LOOKUP or .ENTER, the block number is relative to the 
start of the file. For a non-file-structured .LOOKUP or .EN- 
TER, the block number is the absolute block number on the 
device. Your program should normally update blk before it is 
used again. See the RT—11 Software Support Manual for the 

printers and paper tape punchers 
Request Format: 
RO — > area: 



11 chan 



blk 



buf 



went 



crtn 
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NOTE 

When any .WRITE, .WRITC, or .WRITW programmed re- 
quest is returned, RO contains the number of words requested 
if the write is to a sequential-access device (for example, 
magtape). If the write is to a random-access device (disk or 
DECtape), RO contains the number of words that will be writ- 
ten (.WRITE or .WRITC) or have been written (.WRITW). If a 
request is made to write past the end-of-file on a random- 
access device, the word count is shortened and an error is 
returned. The shortened word count is returned in RO. If a 
write goes past EOF on magtape, the handler returns an er- 
ror and RO = 0. Note that the write is done and a completion 
routine, if specified, is entered, unless the request cannot be 
partially filled (shortened word count = 0). 

When a .WRITC completion routine is entered, the following conditions are 
true: 

1. RO contains the contents of the channel status word for the opera- 
tion. If bit of RO is set, a hardware error occurred during the 
transfer: Consequently, the data may be unreliable. 

2. Rl contains the octal channel number of the operation. This is 
useful when the same completion routine is to be used for several 
different transfers. 

3. Registers RO and Rl are available for use by the routine, but all 
other registers must be saved and restored. Data cannot be passed 
between the main program and completion routines in any regis- 
ter or on the stack. 

Errors: 

Code Explanation 

End-of-file on output. Tried to write outside limits of file. 

1 Hardware error occurred. 

2 Specified channel is not open. 
Example: 

Refer to the example following .READC. 

.WRITW 

The .WRITW request transfers a specified number of words from memory to 
the specified channel. Control returns to your program when the .WRITW 
is complete. 



Macro Call: 
where: 



.WRITW area,chan,buf,wcnt,blk 



area is the address of a five-word EMT argument block 
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chan is a channel number in the range to 376(octal) 

buf is the address of the buffer to be used for output 

went is the number of words to be written. The number must be 
positive 

blk is the block number to be written. For a file-structured 
.LOOKUP or .ENTER, the block number is relative to the 
start of the file. For a non-file-structured .LOOKUP or .EN- 
TER, the block number is the absolute block number on the 
device. Your program should normally update hlk before it is 
used again. See the RT-11 Software Support Manual for the 
significance of the block number for devices such as line 
printers and paper tape punchers 



Request Format 
RO 



area: 



11 chan 



blk 



buf 



went 







NOTE 

When any .WRITE, .WRITC, or .WRITW programmed re- 
quest is returned, RO contains the number of words requested 
if the write is to a sequential-access device (for example, 
magtape). If the write is to a random-access device (disk or 
DECtape), RO contains the number of words that will be writ- 
ten (.WRITE or .WRITC) or have been written (.WRITW). If a 
request is made to write past the end-of-file on a random- 
access device, the word count is shortened and an error is 
returned. The shortened word count is returned in RO. If a 
write goes past end-of-file on magtape, the handler returns 
an error and RO = 0. Note that the write is done and a comple- 
tion routine, if specified, is entered, unless the request cannot 
be partially filled (shortened word count = 0). 

Errors: 

Code Explanation 

Attempted to write past EOF. 

1 Hardware error. 

2 Channel was not opened. 
Example: 

Refer to the example following .READW. 
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Chapter 3 

System Subroutine Description and Examples 



This chapter presents all SYSLIB functions and subroutines in alphabetical 
order and provides a detailed description of each one. An example of each 
call in a FORTRAN program is given. 



3.1 AJFLT 



The AJFLT function converts an INTEGER*4 value to a REAL*4 value 
and returns that result as the function value. 

Form: a = AJFLT (jsrc) 

where: 

jsrc is the INTEGER*4 variable to be converted 
Function Results: 

The function result is a REAL*4 value. 
Errors: 

None. 

Example: 

The following example converts the INTEGER*4 value contained in 
JVAL to single precision (REAL*4), multiplies it by 3.5, and stores 
the result in VALUE. 

REAL*ia VALUE (AJFLT 
INTEGER*^ JMAL 

* 
t 

UALUE = AJFLT( Ji.'AL)*3.5 



3.2 CHAIN 



The CHAIN subroutine allows a background program (or any program in 
the single-job system) to transfer control directly to another background 
program and pass specified information to it. CHAIN cannot be called from 
a completion or interrupt routine. The FORTRAN impure area is not pre- 
served across a chain. Therefore, when chaining from one program to an- 
other, the information must be reset in the program being chained to. 
When chaining to any other program, the user should explicitly close the 
opened logical units with calls to the CLOSE routine. Any routines speci- 
fied in a FORTRAN USEREX library call are not executed if a CHAIN is 
accomplished (see Appendix B in the RT-11/RSTS/E FORTRAN IV User's 
Guide). 
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Form: CALL CHAIN (dblk,var,wcnt) 

where: , 

dblk is the address of a four-word Radix-50 descriptor of the file 
specification for the program to be run (see the PDP-11 FOR- 
TRAN Language Reference Manual for the format of the file 
specification) 

var is the first variable (which must start on a word boundary) in 
a sequence of variables with increasing memory addresses to 
be passed between programs in the chain parameter area (ab- 
solute locations 510 to 777). A single array or a COMMON 
block (or portion of a COMMON block) is a suitable sequence 
of variables 

went is a word count specifying the number of words (beginning at 
var) to be passed to the called program. The argument went 
may not exceed 60. If no words are passed, then a word count 
of must be supplied ] 

If the size of the chain parameter area is insufficient, it can be increased by 
specifying the /B (or /BOTTOM) option to LINK for both the program exe- 
cuting the CHAIN call and the program receiving control. 

The data passed can be accessed through a call to the RCHAIN routine. For 
more information on chaining to other programs, see the .CHAIN pro- 
grammed request (Section 2.6). 

Errors: ' 

None. 

Example: 

The following example transfers control from the main program to 
PROG.SAV on DTO, and passes it variables. 

DIMENSION SPEC(2) 

INTEGER*2 DATA(IO) ) 

DATA SPEC/BRDTOPROi BRG SAU/ 



CALL CHAIN ( SPEC »DATA » 10 ) 



3.3 CLOSEC/ICL0SE 



The CLOSEC subroutine terminates activity on the specified channel and 
frees it for use in another operation. The handler for the associated device 
must be in memory. CLOSEC cannot be called from a completion or inter- 
rupt routine. 

Form: CALL CLOSEC (chan[,i]) 
i = CLOSEC(chan) 
CALL ICLOSE (chan[,i]) 
i = ICLOSE(chan) 
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where: 

chan is the channel number to be closed. This argument must be 
located so that the USR cannot swap over it 

i is the error return if a protection violation occurs 

A CLOSEC or PURGE must eventually be issued for any channel opened 
for input or output. A CLOSEC call specifying a channel that is not open is 
ignored. 

A CLOSEC performed on a iile that was opened via an lENTER causes the 
device directory to be updated to make that file permanent. If the device 
associated with the specified channel already contains a file with the same 
name and type, the old copy is deleted when the new file is made perma- 
nent. If the file name is protected, then a protection error is generated. A 
CLOSEC on a file opened via LOOKUP does not require any directory 
operations. 

When an entered file is closed, its permanent length reflects the highest 
block of the file written since the file was entered; for example, if the 
highest block written is block number 0, the file is given a length of 1; if the 
file was never written, it is given a length of 0. If this length is less than 
the size of the area allocated at lENTER time, the unused blocks are re- 
claimed as an empty area on the device. 

Errors: 

i = Normal return. 
= -4 A protected file with the same name already exists on a 
device. The CLOSEC is performed, resulting in two files on 
the device with the same name. 

Example: 

The following example creates and processes a 56-block file. 

REAL*^ DBLK(2) 

DATA DBLK/BRSYONEW.BRFILDAT/ 

DATA ISIZE/5B/ 



ICHAN=IGETC( ) 

IF( ICHAN.LT.O) GOTO 100 

IERR=IENTER(ICHAN tDBLK .ISIZE) 

IF( IERR,LT.O)GOTO 20 
20 GOTO( 110 >120 .130)ABS( lER) 

CALL ICLOSE (ICHANtI) 

IF( I.EQ.-4) GOTO 200 

CALL IFREEC( ICHAN) 

CALL EXIT 
100 STOP 'NO AVAILABLE CHANNELS' 
110 STOP 'CHANNEL ALREADY IN USE' 
120 STOP 'NOT ENOUGH ROOM ON DEVICE 
130 STOP 'DEVICE IN USE' 
200 STOP 'PROTECTION ERROR' 

END 
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3.4 CONCAT 

The CONCAT subroutine concatenates two character strings. 

Form: CALL CONCAT (a,b,out[,len[,err]]) 

where: 

a is the array containing the left string. The string must be ter- 
minated with a null byte 

b is the array containing the right string. The string must be 
terminated with a null byte 

out is the array into which the concatenated result is placed. This 
array must be at least one element longer than the maximum 
length of the resultant string (that is, one greater than the 
value of len, if specified) 

len is the integer number of characters representing the maximum 
length of the output string. The effect of len is to truncate the 
output string to a given length, if necessary 

err is the logical error flag set if the output string is truncated to 
the length specified by len 

CONCAT sets the string in the array out to be the string in array a imme- 
diately followed on the right by the string in array b and a terminating null 
character. 

NOTE 

Any combination of string arguments is allowed, so long as b 
and out do not specify the same array. 

Concatenation stops when a null character is detected in b, or when the 
number of characters specified by len has been moved. 

If either the left or right string is a null string, the other string is copied to 
out. If both are null strings, then out is set to a null string. The old contents 
of out are lost when this routine is called. 



Errors: 



Error conditions are indicated by err, if specified. If err is given and 
the output string would have been longer than len characters, then 
err is set to .TRUE.; otherwise, err is unchanged. 



Example: 



The following example concatenates the string in array STR and the 
string in array IN and stores the resultant string in array OUT. OUT 
cannot be larger than 29 characters. 



LOGICAL*! IN(2Z) tOUTOO) »STR(7) 



CALL CONCAKSTR .IN.OUT tZ9) 
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3.5 CVTTIM 

) The CVTTIM subroutine converts a two-word internal format time to 

hours, minutes, seconds, and ticks. 

Form: CALL CVTTIM (time,hrs,min,sec,tick) 

where: 

time is the two-word internal format time to be converted. If time 
is considered as a two-element INTEGER*2 array, then: 

time (1) is the high-order time 
time (2) is the low-order time 

hrs is the integer number of hours 

min is the integer number of minutes 

sec is the integer number of seconds 

) tick is the integer number of ticks (1/60 of a second for 60-cycle 

clocks; 1/50 of a second for 50-cycle clocks) 

Errors: 

None. 

Example: 

INTEGER*ii| ITIME 



CALL GTIM(ITIME) !GET CURRENT TIME-OF-DAY 

CALL CVTTIM ( ITIME » IHRS > IMIN t ISEC » ITCK ) 
IF(IHRS.GE.12.AND. IHRS. LT. 13) GOTO 100 ITIME FOR LUNCH 



3.6 DEVICE (FB and XM Only) 



The DEVICE subroutine allows you to set up a list of addresses to be loaded 
with specified values when the program is terminated. If a job terminates 
or is aborted with a CTRL/C from the terminal, this list is picked up by the 
system and the appropriate addresses are set up with the corresponding 
values. 

This function is primarily designed to allow user programs to load device 
registers with necessary values. In particular, it is used to turn off a de- 
vice's interrupt enable bit when the program servicing the device termi- 
nates. 

Only one address list can be active at any given time; hence, if multiple 
DEVICE calls are issued, only the last one has any effect. The list must not 
be modified by the program after the DEVICE call has been issued, and the 
list must not be located in an overlay or an area over which the USE swaps. 

The second argument of the call (link) provides support for a linked list of 
tables. The link argument is optional and causes the first word of the list to 
be processed as the link word. 
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Form: CALL DEVICE (ilist[,link]) 
where: 

ilist is an integer array that contains two-word elements, each 
composed of a one-word address and a one-word value to be 
put at that address, terminated by a zero word. On program 
termination, each value is moved to the corresponding address 

link is an optional argument that can be any value. This indicates 
that a linked list table is to be used 

If the linkeid list form is used the first word of the array is the 
link list pointer 

For more information on loading values into device registers, see the .DE- 
VICE programmed request (Section 2.19). 

Errors: 

None. 

Example: 

INTEGER*2 IDRllO) IDEVICE ARRAY SPEC 

DATA IDR11(1)/"1B7770/ !DR11 CSR ADDRESS (OCTAL) 

DATA IDRll(2)/0/ IVALUE TO CLEAR INTERRUPT ENABLE 

DATA IDRll(3)/0/ ! AND END-OF-LIST FLAG 

CALL DE^ICEdDRll) ! SET UP FOR ABORT 



3.7 DJFLT 



The DJFLT function converts an INTEGER*4 value into a REAL*8 (DOU- 
BLE PRECISION) value and returns that result as the function value. 

Form: d = DJFLT (jsrc) 
where: 

jsrc specifies the INTEGER*4 variable to be converted 
Notes: 

If DJFLT is used, it must be defined in the FORTRAN program, either 
explicitly (REAL*8 DJFLT) or implicitly (IMPLICIT REAL*8 (D)). Without 
a definition, DJFLT is assumed to be REAL*4 (single precision). 

Function Results: 

The function result is the REAL*8 value that is the result of the operation. 

Errors: 

None. 

Example: 

INTEGER*^ JVAL 
REAL*8 DJFLT tD 



D=DJFLT(JVAL) 
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3.8 GETSTR 



The GETSTR subroutine reads a formatted ASCII record from a specified 
FORTRAN logical unit into a specified array. The data is truncated (trail- 
ing blanks removed) and a null byte is inserted at the end to form a charac- 
ter string. 

GETSTR can be used in main program routines or in completion routines, 
but it cannot be used in both at the same time. If GETSTR is used in a 
completion routine, it cannot be the first I/O operation on the specified 
logical unit 

Form: CALL GETSTR (lun,out,len,err) 

where: 

lun is the integer FORTRAN logical unit number of a formatted 
sequential file from which the string is to be read 

out is the array to receive the string; this array must be at least 
one element longer than len 

len is the integer number representing the maximum length of the 
string that is allowed to be input 

err is the LOGICAL*! error flag that is set to .TRUE, if an error 
occurred. If an error did not occur, the flag is .FALSE 

Errors: 

Error conditions are indicated by err. If err is .TRUE., the values 
returned are as follows: 

err = -1 End-of-file for a read operation, 
err = -2 Hard error for a read operation, 
err = -3 More than len bytes were contained in a record. 

Example: 

The following example reads a string of up to 80 characters from 
logical unit 5 into the array STRING. 

LOGICAL*! STRINGCBl) tERR 



CALL GETSTR(5>STRING .SOtERR) 



3.9 GTIM 



The GTIM subroutine returns the current time of day. The time is returned 
in two words and is given in terms of clock ticks past midnight. If the 
system does not have a line clock, a value of is returned. If an RT-11 
monitor TIME command has not been entered, the value returned is the 
time elapsed since the system was bootstrapped, rather than the time of 
day. 
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Form: CALL GTIM (itime) 
where: 

itime is the two- word area to receive the time of day 

The, high-order time is returned in the first word, the low-order time in the 
second word. The CVTTIM routine (see Section 3.5) can be used to convert 
the time into hours, minutes, seconds, and ticks. CVTTIM performs the 
conversion based on the monitor configuration word for 50- or 60-cycle 
clocks. Under an FB or XM monitor, the time-of-day is automatically reset 
after 24:00 when a GTIM is executed; under the single-job monitor, it is 
not. 

Errors 

None. 

Example: 

INTEGER*^ JTIME 



CALL GTIM(JTIME) 

3.10 GTJB/IGTJB 

The GTJB subroutine returns information about a job in the system. 

Form: CALL GTJB (addr,[jobblk [,i]]) 
i = GTJB (addr,[jobblk]) 
CALL IGTJB (addr,Ijobblk [,i]]) 
i = IGTJB (addr,[jobblk]) 



where: 



addr is the address of an eight- or twelve-word block into which 
the parameters are passed 

The parameters returned are as follows: 

Word 1 Job Number = priority level*2 (background 
job is 0, system jobs are 2, 4, 6, 10, 12, 14, 
foreground job is 16 in system job monitors; 
background job is 0, foreground job is 2 in FB 
and XM monitors; job number is in SJ moni- 
tor) 

2 High-memory limit of job partition (last loca- 
tion plus 2) 

3 Low-memory limit of job partition (first loca- 
tion) 

4 Pointer to I/O channel space 

5 Address of job's impure area in FB and XM 
monitors (0 in SJ) 
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6 Low byte: unit number of job's console termi- 
nal (only if the multiterminal option is pres- 
ent; when the multiterminal feature is not 
used) 

7 Virtual high limit for a job created with the 
linker /V option (XM only; in SJ and FB and 
where the Linker /V option is not used) 

8-9 Reserved for future use 
10-12 ASCII , logical job name (system job monitors 
only) 

jobblk is a pointer to a three-word ASCII job name for which data 
is being requested. Do not specify this argument when re- 
questing the eight-word block 

i is an error return if the job is not running 

If one argument is used with the call, only the first eight parameters will be 
passed. For example, 

INTEGER IJPARM(8) 
CALL GTJB (IJPARM) 
I = GTJB (IJPARM) 

At least a comma must follow the argument to pass the information into a 
12-word block. For example, 

INTEGER IJPARM(12) 
CALL GTJB (IJPARM,) 
I = GTJB (IJPARM,) 



Errors: 



i = Normal return. 
= —1 No such job currently running. 



Example: 



C THIS IS AN EXAMPLE UNDER A SYSTEM 
C JOB MONITOR TO SEE IF THE FOREGROUND 
C JOB IS RUNNING 
DIMENSION JDATA(IZ) 



I = GTJB (JDATA. IS) 
IF <I.EO,0) GOTO 20 
TYPE 10 
10 FORMAT( 'NO FG JOB! ') 
STOP 



20 



3.11 GTLIN 



The GTLIN subroutine transfers a line of input from the console terminal 
or an active indirect command file to the user program. This request allows 
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you to input information at the console terminal, and it allows the program 
to operate through indirect files. This subroutine requires the USR. The 
maximum size of the input line is 80 characters. See the .GTLIN pro- 
grammed request for setting bits in the Job Status Word to pass lowercase 
letters and to establish a nonterminating condition. 

Form: CALL GTLIN (result[,prompt]) 

where: 

result is the array receiving the string. This LOGICAL*! array 
contains a maximum of 80 characters plus as the end 
indicator, and therefore must be dimensioned to at least 81 
elements 

prompt is a LOGICAL*! array containing an optional prompt 
string to be printed before the input line is received. The 
string format is the same as that used by the PRINT sub- 
routine. If this argument is not present, no prompt is 
printed 

Errors: 

None. 

Example: 

L0GICAL#1 INP(80) ,PR0MT(6) 

DATA PROMT /' N '. 'A '.' M '. 'E '.'?'," 200/ 



CALL GTLIN( INP»PROMT) 

t 
t 
t 

3.12 lABTIO 

The lABTIO function aborts I/O on a specified channel. 

Form: CALL lABTIO (chan) 

where: 

chan is the channel number for which to abort I/O 
Errors: 

None. 

3.13 lADDR 

The lADDR function returns the ! 6-bit absolute memory address of its 
argument as the integer function value. 

Form: i = lADDR (arg) 
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where: 



arg is the variable or constant whose memory address is to be ob- 
tained. The value obtained by passing an expression as arg is 
unpredictable 



Errors: 

None. 
Example: 



lADDR can be used to find the address of an assembly language 
global area. For example: 



EXTERNAL CAREA 
J=IADDR(CAREA) 



3.14 lAJFLT 



The lAJFLT function converts an INTEGER*4 value to a REAL*4 value 
and stores the result. 

Form: i = lAJFLT (jsrc,ares) 

where: 

jsrc is the INTEGER*4 variable to be converted 

ares is the REAL*4 variable or array element to receive the con- 
verted value 

Function Results: 

i = -1 Normal return; the result is negative. 
= Normal return; the result is 0. 
= 1 Normal return; the result is positive. 

Errors: 

i = -2 Significant digits were lost during the conversion. 
Example: 

INTEGER*^ JVAL 
REAL*fl RESULT 



IF(IAJFLT(jyAL .RESULT) .EO. -2) TYPE 99 
99 FORMAT (' OVERFLOW IN INTEGER*^ TO REAL CONVERSION') 



3.15 lASIQN 



The lASIGN function sets information in the FORTRAN logical unit table 
(overriding the defaults) for use when the FORTRAN Object Time System 
(OTS) opens the logical unit. This function can be used with ICSI (see 
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Section 3.20) to allow a FORTRAN program to accept a standard CSI input 
specification. lASIGN must be called before the unit is opened; that is, 
before any READ, WRITE, PRINT, TYPE, ACCEPT, or OPEN statements 
are executed that reference the logical unit. 

Form: i = lASIGN (lun,idev[,ifiltyp[,isize[,itype]]]) 

where: 



lun 



idev 



ifiltyp 



isize 



itype 



is an INTEGER*2 variable, constant, or expression specify- 
ing the FORTRAN logical unit for which information is 
being specified 

is a one-word Radix-50 device name; this can be the first 
word of an ICSI input or output file specification 

is a three-word Radix-50 file name and file type; this can be 
words 2 through 4 of an ICSI input or output file specifica- 
tion 

is the length (in blocks) to allocate for an output file; this 
can be the fifth word of an ICSI output specification. If 0, the 
larger of either one-half the largest empty segment or the 
entire second largest empty segment is allocated. If the 
value specified for length is -1, the entire largest empty 
segment is allocated 

is an integer value determining the optional attributes to be 
assigned to the file. This value is obtained by adding the 
values that correspond to the desired operations: 

1 Use double buffering for output. 

2 Open the file as a temporary file. 

4 Force a LOOKUP on an existing file during the first 
I/O operation. (Otherwise, the first FORTRAN I/O oper- 
ation determines how the file is opened. Normally if the 
first I/O operation is a write, an lENTER would be per- 
formed on the specified logical unit. A read always 
causes a LOOKUP.) 
8 Expand carriage control information (see Notes below). 
16 Do not expand carriage control information. 
32 File is read only. 



Notes: 



Expanded carriage control information applies only to formatted output 
files and means that the first character of each record is used as a carriage 
control character when processing a write operation to the given logical 
unit. The first character is removed from the record and converted to the 
appropriate ASCII characters to simulate the requested carriage control. 

If carriage control information is not expanded, the first character of each 
record is unmodified and the FORTRAN OTS outputs a line feed, followed 
by the record, followed by a carriage return. 

If carriage control is unspecified, the FORTRAN OTS sends expanded car- 
riage control information to the terminal and line printer and sends unex- 
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panded carriage control information to all other devices and files. See the 
PDP-11 FORTRAN Language Reference Manual for further carriage con- 
trol information. 



Errors: 



i = Normal return. 

<> The specified logical unit is already in use, or there is no 
space for another logical unit association. 



Example: 



The following example (1) creates an output file on logical unit 3, 
using the first output file given to the RT-11 Command String Inter- 
preter (CSI), (2) sets up the output file for double buffering, (3) cre- 
ates an input file on logical unit 4, based on the first input file specifi- 
cation given to the RT-11 CSI, and (4) makes the input file available 
for read-only access. 



INTEGER*2 SPEC(39) 

REAL*4 E);T(2) 

DATA EXT/GRDATDAT»BRDATDAT/ 



IDEFAULT FILE TYPE IS DAT 



3.16 ICDFN 



10 IFdCSKSPEC (EXT . » .0) .NE.O) GOTO 10 

C 

C DO NOT ACCEPT ANY SWITCHES 

C 

CALL lASIGNO .SPEC(l) tSPEC(2) »SPEC(5) »1) 
CALL lASIGNCa .SPEC(IS) »SPEC(17) ,0,32) 



The ICDFN function increases the number of input/output channels. Note 
that ICDFN defines new channels; any channels defined with an earlier 
ICDFN function are not used. Thus, an ICDFN for 20(decimal) channels 
(while the 16[decimal] original channels are defined) causes only 20 I/O 
channels to exist; the space for the original 16 is unused. The space for the 
new channel area is allocated out of the free space managed by the FOR- 
TRAN system. 

Form: i = ICDFN (num[,area]) 

where: 

num is the integer number of channels to be allocated. The number 
of channels must be greater than 16 and can be a maximum of 
256. The program can use all new channels greater than 16 
without a call to IGETC; the FORTRAN system input/output 
uses only the first 16 channels. This argument must be posi- 
tioned so that the USR cannot swap over it 

area is the space allocated from within the calling program. Under 
FB and SJ monitors; be sure that the space is outside the USR 
swapping area. If this argument is not specified, the space for 
the channels is allocated in the FORTRAN OTS work area 
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Notes: 

1. ICDFN cannot be issued from a completion or interrupt routine. 

2. It is recommended that the ICDFN function be used at the beginning of 
the main program before any I/O operations are initiated. 

3. If ICDFN is executed more than once, a completely new set of channels 
is created each time ICDFN is called. 

4. ICDFN requires that extra memory space be allocated to foreground 
programs (see Section 1.2.4.1). 

5. Any channels that were open prior to the ICDFN are copied over to the 
new set of channel status tables. 

Function Results: 

i = Normal return. 
= 1 An attempt was made to allocate fewer channels than al- 
ready exist. 
= 2 Not enough free space is available for the channel area. 

Example: 

IF( ICDFN(Z4) .E0.2) STOP 'NOT ENOUGH MEMORY' 

3.17 fCHCPY (FB and XM Only) 

The ICHCPY function opens a channel for input, logically connecting it to a 
file that is currently open by another job for either input or output. This 
function can be used by either the foreground or the background job. An 
ICHCPY must be done before the first read or write for the given channel. 

Form: i = ICHCPY (chan,ochan[,jobblk]) 

where: 

chan is the channel the job will use to read the data. You must 
obtain this channel through an IGETC call, or you can use 
channel 16 or higher if you have done an ICDFN call 

ochan is the channel number of the other job that is to be copied 

jobblk is a pointer to a three-word ASCII job name 

Notes: 

1. If the other ^ob's channel was onened with an lENTER function or a 
.ENTER programmed request to create a file, your channel indicates a 
file that extends to the highest block that the creator of the file had 
written at the time the ICHCPY was executed. 

2. A channel that is open on a sequential-access device should not be 
copied, because buffer requests can become intermixed. 



3-14 System Subroutine Description and Examples 



3. Your program can write on a copied channel to a file that is being 
created by the other job, just as your program could if it were the crea- 
tor. When your channel is closed, however, no directory update takes 
place. 

Errors: 

i = Normal return. 
= 1 Specified job does not exist or does not have the specified 

channel iochan) open. 
= 2 Channel (chan) is already open. 

3.18 ICLOSE 

See the SYSLIB subroutine CLOSEC. 

3.19 ICMKT 

The ICMKT function cancels one or more scheduling requests (made by an 
ISCHED, ITIMER, or MRKT routine). Support for ICMKT in SJ requires 
that timer support be created through SYSGEN. 

Form: i = ICMKT (id,time) 

where: 

id is the identification integer of the request to be canceled. If id 

is equal to 0, all scheduling requests are canceled 

time is the name of a two-word area in which the monitor returns 
the amount of time remaining in the canceled request 

For further information on canceling scheduling requests, see the .CMKT 
programmed request (Section 2.9). 

Errors: 

i = Normal return. 
= 1 id was not equal to and no scheduling request with that 
identification could be found. 

Example: 

INTEGER*^ J 

♦ 
t 

CALL ICMKT(0»J) ! ABORT ALL TIMER REQUESTS NOW 

« 

4 
« 

END 
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3.20 ICSI 



The ICSI function calls the RT-11 Command String Interpreter in special 
mode to parse a command string and return file descriptors and options to 
the program. In this mode, the CSI does not perform any handler 
IFETCHes, CLOSECs, lENTERs, or LOOKUPS. ICSI cannot be called from 
a completion or interrupt routine. This subroutine requires the USR. 

Form: i = ICSI (filspc,deftyp,[cstring],[option],n) 

where: 

filspc is the 39-word area to receive the file specifications. The 
format of this area (considered as a 39-element INTE- 
GER*2 array) is: 

Word 



1 


output file number 1 


4 


specification 


5 


output file number 1 length 


6 


output file number 2 


9 


specification 


10 


output file number 2 length 


11 


output file number 3 


14 


specification 


15 


output file number 3 length 


16 


input file number 1 


19 


specification 


20 


input file number 2 


23 


specification 


24 


input file number 3 


27 


specification 


28 


input file number 4 


31 


specification 


32 


input file number 5 


35 


specification 


36 


input file number 6 


39 


specification 



deft3rp is the table of Radix-50 default file types to be assumed 
when a file is specified without a file type: 

deftyp(l) is the default for all input file types 

deftyp(2) is the default file type for output file number 1 

deftjT)(3) is the default file tjrpe for output file number 2 

deft5np(4) is the default file type for output file number 3 

cstring is the area that contains the ASCIZ command string to be 
interpreted; the string must end in a zero byte. If the argu- 
ment is omitted, the system prints the prompt character (*) 
at the terminal and accepts a command string. If input is 
from an indirect command file, the next line of that file is 
used 
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option 



n 



is the name of an INTEGER*2 array dimensioned (4,n) 
where n represents the number of options defined to the 
program. This argument must be present if the value speci- 
fied for n is non-zero. This array has the following format 
for the jth option described by the array: 

optiondj) is the one-character ASCII name of the option 
option(2,j) is set by the routine to 0, if the option did not 

occur; to 1, if the option occurred without a 

value; to 2, if the option occurred with a value 
option(3,j) is set to the file number on which the option is 

specified 
option(4,j) is set to the specified value if option(2,n) is 

equal to 2 

is the number of options defined in the array option 



Notes: 



1. The array option must be set up to contain the names of the valid 
options. For example, use the following to set up names for five options: 

INTEGER#2 Q\A{a t5) 

DATA SW(1»1)/'S'/»SW(1,2)/'M'/»SW(1,3)/'I'/ 

DATA SW(l,a)/'L'/,SW(l,5)/'E'/ 

2. Multiple occurrences of the same option are supported by allocating an 
entry in the option array for each occurrence of the option. Each time 
the option occurs in the option array, the next unused entry for the 
named option is used. 

The arguments of ICSI must be positioned so that the USR cannot swap 
over them. For more information on calling the Command String Inter- 
preter, see the .CSISPC programmed request (Section 2.14). 



3. 



Errors: 



i = Normal return. 
= 1 Illegal command line; no data was returned. 
= 2 An illegal device specification occurred in the string. 
= 3 An illegal option was specified, or a given option was spec- 
ified more times than were allowed for in the option array. 



Example: 



The following example causes the program to loop until a valid com- 
mand is typed at the console terminal. 



INTEGER*2 SPEC(39) 

REAL*4 EXT(2) 

DATA EXT/6RDATDAT tBRDATDAT/ 



10 TYPE 99 

99 FORMAT ( ' ENTER VALID C9I BTRING WITH NO 
IF( ICSI (SPECtEXT I , »0) .NE.O) GOTO 10 



OPTIONS' ) 
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3.21 ICSTAT 

The ICSTAT function obtains information about a channel. 

Form: i = ICSTAT (chan,addr) 

where: 

is the channel whose status is desired 



chan 
addr 



Errors: 



is a six-word area to receive the status information. The area, 
as a six-element INTEGER*2 array, has the following format: 

Word 1 channel status word 

2 starting absolute block number of file on this chan- 
nel 

3 length of file 

4 highest block number written since file was opened 

5 unit number of device with which this channel is 
associated 

6 Radix-50 of device name with which the channel is 
associated 



i — Normal return. 
= 1 Channel specified is not open. 



Example: 



The following example obtains channel status information about 
channel I. 



39 



INTEGER*2 AREA(S) 

1=7 

IFdCSTATd »AREA) .NE.O) TYPE 99»I 

FORMATdKt 'CHANNEL' tI4 »'IS NOT OPEN') 



3 55 inPi PT 
B^^ ^ a-ijF IL» i». i»» I 



The IDELET function deletes a named file from an indicated device. 
IDELET requires the USR and cannot be issued from a completion or inter- 
rupt routine. 

Form: i = IDELET (chan,dblk[,seqnum]) 

where: 

chan is the channel to be used for the delete operation. You 

must obtain this channel through an IGETC call, or you 
can use channel 16(decimal) or higher if you have done an 
ICDFN call 

dblk is the four-word Radix-50 specification (dev:filnam.t3rp) 

for the file to be deleted 



3—18 System Subroutine Description and Examples 



seqnum is the file number for cassette operations: if this argument 
is blank, a value of is assumed 

For magtape operation, it describes a file sequence number that 
can have the following values: 

Value Meaning 

-1 This value suppresses rewinding and searching for a file 
name from the current tape position. Note that if the 
position is unknown, the handler executes a positioning 
algorithm that involves backspacing until an end-of-file 
label is found. The user should not use any other value 
since all other negative values are reserved for future 
use. 

This value rewinds the magtape and spaces forward un- 
til the file name is found. 

n Where n is any positive number. This value positions 
the magtape at file sequence number n. If the file repre- 
sented by the file sequence number is greater than two 
files away from the beginning of the tape, a rewind is 
performed. If not, the tape is backspaced to the file. 

NOTE 

The arguments of IDELET must be located so that the USR 
cannot swap over them. 



j The specified channel is left inactive when the IDELET is complete. IDE- 

LET requires that the handler to be used be resident (via an IFETCH call 
or a LOAD command from KMON) at the time the IDELET is issued. If the 
handler is not resident, a monitor error occurs. 

For further information on deleting files, see the .DELETE programmed 
request (Section 2.18). 



Errors: 



Normal return. 

1 Channel specified is already open. 

2 File specified was not found. 

3 Device in use. 

4 The file is protected and cannot be deleted. 



Example: 



T^l ^^11 .: 1„ J_1_J _ r:i_ ] TirmvTr t-v a m r—--^- rc»7-/\ 

xiic luiiuwiiig cAtiiiipic utjietea a me iiuiimu r xiNO.U'rt.x irom OIU. 

REAL*^ FILNAM(2) 

DATA FILNAM/BRSY0FTN»BR5 DAT/ 



I = IGETC( ) 

IF(I.LT.O) STOP 'NO CHANNEL' 

CALL IDELETd »FILNAM) 

CALL IFREEC(I) 
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3.23 IDJFLT 



The IDJFLT function converts an INTEGER*4 value into a REAL*8 (DOU- 
BLE PRECISION) value and stores the result. 

Form: i = IDJFLT {jsrc,dres) 

where: 

jsrc specifies the INTEGER*4 variable that is to be converted 

dres specifies the REAL*8 (or DOUBLE PRECISION) variable to 
receive the converted value 

Function Results: 

i = -1 Normal return; the result is negative. 
= Normal return; the result is 0. 
= 1 Normal return; the result is positive. 

Errors: 

None. 

Example: 



INTEGER#a JJ 
REAL*8 DJ 



99 



IF( IDJFLK JJ »DJ) .LE.O) TYPE 99 
FORMAT (' VALUE IS NOT POSITIVE') 



3.24 IDSTAT 



The IDSTAT function obtains information about a particular device. It re- 
quires the USR and cannot be issued from a completion or interrupt rou- 
tine. 



Form: 
where: 



= IDSTAT (devnam,cblk) 



devnam is the Radix-50 device name 

cblk is the four-word area used to store the status information. 

The area, as a four-element INTEGER*2 array, has the 
following format: 

Word 1 device status word (see Section 2.29) 

2 size of handler in bytes 

3 entry point of handler (non-zero implies that 
the handler is in memory) 

4 size of the device (in 256-word blocks) for 
block-replaceable devices; zero for sequential- 
access devices 
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NOTE 

The arguments of IDSTAT must be positioned so that the 
USR cannot swap over them. 

IDSTAT looks for the device specified by devnam and, if found, returns four 
words of status in cblk. 



Errors: 



i = Normal return. 
= 1 Device not found in monitor tables. 



Example: 



The following example determines whether the line printer handler 
is in memory. If it is not, the program stops and prints a message to 
indicate that the handler must be loaded. 



INTEGER IDNAM 

INTEGER*2 CBLK(a) 

DATA IDNAM/3RLP / 

DATA CBLK/^»0/ 

CALL IDSTATdDNAM fCBLK) 

IF(CBLK(3) .EO.O) STOP 'LOAD 



THE LP HANDLER AND RERUN' 



3.25 lEMTER 



The lENTER function allocates space on the specified device and creates a 
tentative directory entry for the named file. If a file of the same name 
already exists on the specified device, it is not deleted until the tentative 
entry is made permanent by CLOSEC or ICLOSE. The file is attached to 
the channel number specified. This routine requires the USR. 

Form: i = lENTER (chan,dblk,length[,seqnum]) 

where: 

chan is the integer specification for the RT-11 channel to be 

associated with the file. You must obtain this channel 
through an IGETC call, or you can use channel 16 or 
higher if you have done an ICDFN call 

dblk is the four-word Radix-50 descriptor of the file to be oper- 

ated upon 

leneth is the intesrer nnmhfir nf Klnr-ta tn ho allo-Qfori frxv fUo fii^ 
If 0, the larger of either one-half the largest empty seg- 
ment or the entire second largest empty segment is allo- 
cated. If the value specified for length is -1, the entire 
largest empty segment is allocated (see the .ENTER pro- 
grammed request, Section 2.32) 

seqnum is a file number for cassette. If this argument is blank, a 
value of is assumed. 
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For magtape, it describes a file sequence number that can 
have the following values: 

-2 Rewind the magtape and space forward until the file 
name is found, or until logical-end-of-tape is de- 
tected. The magtape is now positioned correctly. A 
new logical-end-of-tape is implied. 

-1 Space to the logical-end-of-tape and enter file. 

Rewind the magtape and space forward until the file 
name is found or the logical-end-of-tape is detected. 
If the file name is found, an error is generated. If the 
file name is not found, then enter file. 

n Position magtape at file sequence number n if n is 
greater than zero and the file name is not null. 

Notes: 

1. lENTER cannot be issued from a completion or interrupt routine. 

2. lENTER requires that the appropriate device handler be in memory. 

3. The arguments of lENTER must be positioned so that the USR does not 
swap over them. 

For further information on creating tentative directory entries, see the 
.ENTER programmed request (Section 2.32). 

Errors: 

i = n Normal return; number of blocks actually allocated {n = 
for non-file-structured lENTER). 
= -1 Channel (chan) is already in use. 
= -2 In a fixed-length request, no space greater than or equal 

to length was found. 
= -3 Device in use. 

= -4 A file by that name already exists and is protected. 
= -5 File sequence number not found. 

Example: 

The following example allocates a channel for file TEMP.TMP on 
SYO. If no channel is available, the program prints a message and 
halts. 

REAL*4 DBLK(2> 

DftTA DBLK/BRSYOTEM ,BRP TMP/ 

ICHAN=IGETC( ) 

IFdCHAN.LT.O) STOP 'NO AVAILABLE CHANNEL' 

C 

C CREATE TEMPORARY WORK FILE 



C 



IF(IENTER(ICHAN»DBLK .20) .LT.O) STOP 'ENTER FAILURE' 



CALL PURGE(ICHAN) 
CALL IFREEC(ICHAN) 
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3.26 IFETCH 



The IFETCH function loads a device handler into memory from the system 
device, making the device available for input/output operations. The han- 
dler is loaded into the free area managed by the FORTRAN system. Once 
the handler is loaded, it cannot be released and the memory in which it 
resides cannot be reclaimed. IFETCH requires the USR and cannot be is- 
sued from a completion or interrupt routine. IFETCH issued from a fore- 
ground job will fail unless the handler is already in memory. 

Form: i = IFETCH (devnam) 

where: 

devnam is the one- word Radix-50 name of the device for which the 
handler is desired. This argument can be the first word of 
an ICSI input or output file specification. This argument 
must be positioned so that the USR cannot swap over it 

For further information on loading device handlers into memory, see the 
.FETCH programmed request (Section 2.34). 

Errors: 

i = Normal return. 
= 1 Device name specified does not exist. 
= 2 Not enough room exists to load the handler. 
= 3 No handler for the specified device exists on the system 
device. 

Example: 

The following example requests that the DX handler be loaded into 
memory; execution stops if the handler cannot be loaded. 

REAL»a IDNAM 
DATA IDNAM/3RDX/ 



IF (IFETCHC IDNAM) .NE.O) STOP 'FATAL ERROR FETCHING HANDLER' 

3.27 IFPROT 

The IFPROT function sets or removes file protection for a file. 

Form: i = IFPROT (chan,filspc,prot) 

where: 

chan is the channel number to be used for the protect operation. 
You must obtain this channel through an IGETC call, or you 
can use the channel 16(decimal) or higher if you have done 
an ICDFN call 

filspc is the file specification of the file to be protected or unpro- 
tected, in Radix— 50 



prot 1 = protect the file 

= remove protection from the file 
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Errors: 

i = Normal return. 

= 1 Channel is in use. 

= 2 File not found. 

= 3 Invalid operation. 

= 4 Invalid prot value. 

Example: 

This example protects the file SY:RT11FB.SYS against deletion. 

ICHAN = IGETCO ! ALLOCATE CHANNEL 

IF (ICHAN. LT.O) STOP 'CANNOT ALLOCATE CHANNEL' 
I = IFPROT( ICHAN. ' BY : RT 1 IFB . SYS ' ,1 ) 



END 



3.28 IFREEC 



The IFREEC function returns a specified RT-11 channel to the available 
pool of channels. Before IFREEC is called, the specified channel must be 
closed or deactivated with a CLOSEC or ICLOSE (see Section 3.3) or a 
PURGE (see Section 3.92) call. IFREEC cannot be called from a completion 
or interrupt routine. IFREEC calls must be issued only for channels that 
have been successfully allocated by IGETC calls; otherwise, the results are 
unpredictable. 

Form: i = IFREEC (chan) 

where: 

chan is the integer number of the channel to be freed 

Errors: 

i = Normal return. 
= 1 Specified channel is not currently allocated. 

Example: 

See the example under IGETC. 



3.29 IGETC 



The IGETC function allocates an RT-11 channel, in the range to 15(deci- 
mal), to be used by other SYSLIB routines and marks it in use so that the 
FORTRAN I/O system will not access it. IGETC cannot be issued from a 
completion or interrupt routine. 

Form: i = IGETCO 

Function Result: 

i = n Channel n has been allocated. 
Error: 

i = -1 No channels are available. 
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Example: 



ICHAN=IGETC( ) ! ALLOCATE CHANNEL 

IF( ICHAN.LT.O) STOP 'CANNOT ALLOCATE CHANNEL' 



CALL IFREECC ICHAN) 



!FREE IT WHEN THROUGH 



END 



3.30 IGETSP 



The IGETSP subroutine obtains free space from the FORTRAN system and 
returns the address and size (in number of words) of the allocated space. 
When this space is obtained, it is allocated for the duration of the program. 

Form: i = IGETSP (min,max,iaddr) 

where: 

min is the minimum space to be obtained without an error indi- 
cating that the desired amount of space is not available 

max is the maximum space to be obtained 

iaddr is the integer specifying the address of the start of the free 
space (buffer). Note that iaddr does not directly denote the 
storage area as a standard FORTRAN variable would. 
Rather, it denotes a word that contains the address of the 
storage space. It is most useful with IPEEK and IPOKE, or 
with assembly language subroutines 

NOTE 

Extreme caution should be exercised to avoid using all of the 
free space allocated by the FORTRAN system. If the FOR- 
TRAN system runs out of dynamic free space, fatal errors 
(Error 29, 30, 42, and so forth) occur. See the RT-11 System 
Message Manual. 

Function Results: 

i = n The actual size allocated whose value is min .LE. n .LE. 
max. The size (min, max, n) is specified in words. 



Error: 



-1 Not enough free space is available to meet the minimum 
requirements; no allocation was taken from the FORTRAN 
system free space. 



Example: 



N = IGETSP(25B ,25B . I BUFF) 

IF(N.LT.O) STOP 'CANNOT GET BUFFER SPACE! 



!GET 25G WORD BUFFER 
!N0 SPACE AVAILABLE 
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3.31 IGTJB 

See the SYSLIB subroutine GTJB, Section 3.10. 



3.32 UCVT 



The UCVT function converts an INTEGER*4 value to INTEGER*2 format. 
If ires is not specified, the result returned is the INTEGER*2 value of jsrc. 
If ires is specified, the result is stored there. 

Form: i = UCVT (jsrc[,ires]) 

where: 

jsrc specifies the INTEGER*4 variable or array element whose 
value is to be converted 

ires specifies the INTEGER*2 entity to receive the conversion re- 
sult 

Function Results (if ires is specified): 

i = -2 An overflow occurred during conversion. 

= -1 Normal return; the result is negative. 

= Normal return; the result is 0. 

= 1 Normal return; the result is positive. 

Errors: 

None. 

Example: 

INTEGER*^ jyAL 
INTEGER»2 IMAL 



IF( IJCUT( JMAL ,IUAL) .E0,-2) TYPE 99 
99 FORMAK' NUMBER TOO LARGE IN IJCUT C0NUER9I0N') 

3.33 ILUN 

The ILUN function returns the RT-11 channel number with which a FOR- 
TRAN logical unit is associated. 

Form: i = ILUN (lun) 

where: 

lun is an integer expression whose value is a FORTRAN logical 
unit number in the range 1-99 

Function Results: 

= +n RT-11 channel number n is associated with lun. 

Errors: 

i = -1 Logical unit is not open. 
= -2 Logical unit is opened to console terminal. 
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Example: 



PRINT 93 
99 FDRMAK ' PRINT DEFAULTS TO LOGICAL UNIT B . WHICH FURTHER DEFAULTS TO LP: ' ) 
ICHAN=ILUN(B) IWHICH RT-11 CHANNEL IS RECEIVING I/O? 



3.34 INDEX 



The INDEX subroutine searches a source string for the occurrence of a 
pattern string and returns the character position of the first occurrence of 
the pattern within the source. 

Form: CALL INDEX (a,pattrn,[i],m) 



or 
m = 



where: 



pattrn 



m 

Errors: 

None. 
Example: 



INDEX (a,pattrn[,i]) 



is the array containing the source string to be searched; it 
must be terminated by a null byte 

is the string being sought; it must be terminated by a null 
byte 

is the integer starting character position of the search in a. 
If i is omitted, a is searched beginning at the first character 
position 

is an integer variable to store the result of the search; m is 
set to the starting character position oi pattrn in a, if found; 
otherwise m is 



The following exam.ple searches the array STRING for the first occur- 
rence of strings EFG and XYZ and searches the string ABC ABCABC 
for the occurrence of string ABC after position 5. 



CALL SCOPY( 'ABCDEFGHI ' .STRING) 
CALL INDEX(STRING . 'EFG' . .M) 
CALL INDEX(STRING . 'XYZ' . »N) 
CALL INDEX( 'ABCABC ABC . 'ABC (5 .L) 



! INITIALIZE STRING 
!M = 5 
!N = 
!L = 7 



3.35 INSERT 



The INSERT subroutine replaces a portion of one string with another 
string. 

Form: CALL INSERT (in,out,i[,m]) 
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where: 



in 



out 



is the array containing the string being inserted. The string 
must be terminated with a null if the number of characters is 
less than the value of m (below), or if m is not specified 

is the array containing the string being modified. The string 
must be terminated with a null 

i is the integer specifying the character position in out at which 

the insertion begins 

m is the integer maximum number of characters to be inserted 

If the maximum number of characters (m) is not specified, all characters to 
the right of the specified character position (i) in the string being modified 
are replaced by the string being inserted. The insert string {in) and the 
string being modified {out) can be in the same array only if the maximum 
number of characters (m) is specified and is less than or equal to the differ- 
ence between the position of the insert (i) and the maximum string length 
of the array. 

Errors: 

None. 

Example: 



CALL SCOPY( 'ABCDEFGHIJ' »S1) 
CALL SC0PY(S1 iS2) 
CALL INSERT( '123' »S1 »B »3) 
CALL INSERT( '123' .82,^) 



! INITIALIZE STRING 1 
! INITIALIZE STRING 2 
!S1 = 'ABCDE123IJ' 
!S2 = 'ABC123' 



3.36 INTSET 



The INTSET function establishes a FORTRAN subroutine as an interrupt 
service routine, assigns it a priority, and attaches it to a vector. INTSET 
requires that extra memory be allocated to foreground programs that use it 
(see Section 1.2.4.1). 

Form: i = INTSET (vect,pri,id,crtn) 

where: 

vect is the integer specifying the address of the interrupt vector to 
which the subroutine is to be attached 

pri is the integer specifying the actual priority level (4—7) at 
which the device interrupts 

id is the identification integer to be passed as the single argu- 
ment to the FORTRAN routine when an interrupt occurs. 
This allows a single crtn to be associated with several INTSET 
calls 
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crtn 



is a FORTRAN subroutine to be established as the interrupt 
routine. This name should be specified in an EXTERNAL 
statement in the FORTRAN program that calls INTSET. The 
subroutine has one argument: 

SUBROUTINE crtn(id) 
INTEGER id 

When the routine is entered, the value of the integer argu- 
ment is the value specified for id in the appropriate INTSET 
call 



Notes: 



1. The id argument can be used to distinguish between interrupts from 
different vectors if the routine to be activated services multiple devices. 

2. When using INTSET in FB or XM, the SYSLIB call DEVICE must be 
used in almost all cases to prevent interrupts from interrupting beyond 
program termination. 

3. If the interrupt routine {crtn) has control for a period of time longer 
than the time in which two more interrupts using the same vector 
occur, interrupt overrun is considered to have occurred. The error mes- 
sage: 

?SYSLIB-F-Interrupt overrun 

is printed and the job is aborted. Jobs requiring very fast interrupt 
response are not viable with FORTRAN, since FORTRAN overhead 
lowers RT-ll's interrupt response rate. 

4. The interrupt routine {crtn) is actually run as a completion routine by 
the RT-11 .SYNCH macro. The pri argument is used for the RT-11 
.INTEN macro. 

5. A .PROTECT request is issued for the vector, but no attempt is made to 
report an error if the vector is already protected; furthermore, the vec- 
tor is taken over unconditionally. See the .PROTECT programmed re- 
quest (Section 2.64) for more information. 

6. The FORTRAN interrupt service subroutine {crtn) cannot call the USR. 

7. INTSET cannot be called from a completion or interrupt routine. 

8. Interrupt enable should not be set on the associated device until the 
INTSET call has been successfullv executed. 



Errors: 



Normal return. 

1 Invalid vector specification. 

2 Reserved for future use. 

3 No space is available for the linkage setup. 
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Example: 

EXTERNAL CLKSUB ! BUBR TO HANDLE KWll-P CLOCK 



I=INTSET("104»BtO»CLKSUB) ! ATTACH ROUTINE 
IF (I.NE.O) GOTO 100 ! BRANCH IF ERROR 



END 

SUBROUTINE CLKSUB( ID) 



END 

3.37 IPEEK 



The IPEEK function returns the contents of the word located at a specified 
absolute 16-bit memory address. This function can examine device registers 
or any location in memory. 

Form: i = IPEEK (iaddr) 

where: 

iaddr is the integer specification of the absolute address to be exa- 
mined. If this argument is not an even value, a trap results 
(except on LSI-11 or a PDP-11/23) 

Function Result: 

The function result (i) is set to the value of the word examined. 

Example: 

ISWIT = IPEEK( "177570) ! GET VALUE OF CONSOLE SWITCHES 



3.38 IPEEKB 



The IPEEKB subroutine returns the contents of a byte located at a speci- 
fied absolute byte address. Since this routine operates in a byte mode, the 
address supplied can be odd or even. This subroutine can examine device 
registers or any byte in memory. The return is zero extended, that is, the 
high byte is 0. 

Form: i = IPEEKB (iaddr) 

where: 

iaddr is the integer specification of the absolute byte address to be 
examined. Unlike the IPEEK subroutine, the IPEEKB sub- 
routine allows odd addresses 

Function Result: 

The function result (i) is set to the value of the byte examined. 

Example: 

lERR = IPEEKB("53) !Get error byte 
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3.39 IPOKE 



The IPOKE subroutine stores a specified 16- bit integer value into a speci- 
fied absolute memory location. This subroutine can store values in device 
registers. 

Form: CALL IPOKE (iaddr.ivalue) 

where: 



iaddr 



ivalue 



is the integer specification of the absolute address to be 
modified. If this argument is not an even value, a trap re- 
sults (except on LSI-11 or PDP-11/23) 

is the integer value to be stored in the given address speci- 
fied by the iaddr argument 



Errors: 

None. 
Example: 



The following example displays the value of IVAL in the console 
display register (this is possible only on certain processors). 

CALL IP0KE("177570,IMAL) 

To set bit 12 in the JSW without zeroing any other bits in the JSW, 
use the following procedure. 

CALL I POKE ( "au ."10000. OR. I PEEK ("4-^) ) 



3.40 IPOKEB 



The IPOKEB subroutine stores a specified eight-bit integer value into a 
specified byte location. Since this routine operates in a byte mode, the 
address supplied can be odd or even. This subroutine can store values in 
device registers. 

Form: CALL IPOKEB (iaddr,ivalue) 

where: 

iaddr is the integer specification of the absolute address to be 
modified. Unlike the IPOKE subroutine, the IPOKEB sub- 
routine allows odd addresses 

ivalue is the integer value to be stored in the given address speci- 
fied by the iaddr argument 

Errors: 

None. 

Example: 

CALL IP0KEB("53."Z0) ! Tell KMDN unconditionally fatal error 
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3.41 fPUT 



The IPUT function replaces the value of a monitor fixed offset. IPUT uses 
the monitor .PVAL programmed request. 

Form: i = IPUT (ioff, value) 

where: 

ioff is the offset (from the base of RMON) to be modified 

value is the integer value to replace the current contents of the 
offset location 

Function Result: 

i = old (replaced) value of the fixed offset location. 

Example: 

ISIZE = IPUT ("314) 100) ! Chanse default fiJe size used by ENTER 

3.42 IQSET 

The IQSET function is used to make the RT-11 I/O queue larger — that is, 
to add available elements to the queue. These elements are allocated out of 
the free space managed by the FORTRAN system. IQSET cannot be called 
from a completion or interrupt routine. 

Form: i = IQSET (qleng[,area]) 

where: 

qleng is the integer number of elements to be added to the queue. 
This argument must be positioned so that the USR does not 
swap over it 

area is the space allocated from within the calling program. Un- 
der FB and SJ monitors, make sure that the space is outside 
the USR swapping area. If this argument is not specified, the 
space for the elements is allocated in the FORTRAN OTS 
work area 

All RT-11 I/O transfers are done through a centralized queue management 
system. If I/O traffic is very heavy and not enough queue elements are 
available, the program issuing the I/O requests is suspended until a queue 
element becomes available. In an FB or XM system, the other job can run 
while the first program waits for the element. When IQSET is used in a 
nrocram to be run in the forecround, the FRUN command must be modified 
to allocate space for the queue elements (see Section 1.2.4.1). 

A general rule to follow is that each program should contain one more 
queue element than the total number of I/O and timer requests that will be 
active simultaneously. Timing functions such as ITWAIT and MRKT also 
cause elements to be used and must be considered when allocating queue 
elements for a program. Note that if synchronous I/O is done (for example, 
IREADW/IWRITW) and no timing functions are done, no additional queue 
elements need be allocated. Note also that FORTRAN IV allocates four 
queue elements by default. 
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The following subroutines require queue elements: 

IRCVD/IRCVDC/IRCVDF/IRCVDW ITIMER 
IREAD/IREADC/IREADF/IREADW ITWAIT 
ISCHED lUNTIL 

ISDAT/ISDATC/ISDATF/ISDATW IWRITE/IWRITC/IWRITF/IWRITW 
ISLEEP MRKT 

ISPFN/ISPFNC/ISPFNF/ISPFNW MWAIT 

For further information on adding elements to the queue, see the .QSET 
programmed request. 

Errors: 

i = Normal return. 
= 1 Not enough free space is available for the number of 
queue elements to be added; no allocation was made. 

Example: 

IF(I0SET(5) .NE.O) STOP 'NOT ENOUGH FREE SPACE FOR QUEUE ELEMENTS' 



^ 3.43 IRAD50 

The IRAD50 function converts a specified number of ASCII characters to 
Radix-50 and returns the number of characters converted. Conversion 
stops on the first non-Radix-50 character encountered in the input, or when 
the specified number of ASCII characters have been converted. 

Form: n = IRAD50 (icnt,input,output) 

where: 
) 

n is the integer number of input characters actually con- 

nected 

icnt is the number of ASCII characters to be converted 

input is the area from which input characters are taken 

output is the area in which Radix-50 words are stored 

Three characters of text are packed into each word of output. The number 
) of output words modified is computed by the expression (in integer words): 

(icnt^2)/3 

Thus, if a count of 4 is specified, two words of output are written even if 
only a one-character input string is given as an argument. 

Function Result: 

The inteo'er number of in^ut characters actually converted (n) is returned 
as the function result. 

Example: 

REAL*8 FSPEC 

CALL IRAD50(12.'SY0TEMP DAT'tFSPEC) 

3.44 IRCVD/IRCVDC/IRCVDF/IRCVDW (FB and XM Only) 

) There are four forms of the receive data function; these are used in conjunc- 

tion with the ISDAT (send data) functions to allow a general data/message 
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transfer system. The receive data functions issue RT-H receive data pro- 
grammed requests (see Section 2.70). These functions require a queue ele- 
ment; this should be considered when the IQSET function (Section 3.42) is 
executed. 

IRCVD 

The IRCVD function receives data and continues execution. The operation 

is queued and the issuing job continues execution. When the job has to 

receive the transmitted message, an MWAIT should be executed. This 

causes the job to be suspended until all pending messages have been 

received. 

Form: i = IRCVD (buff.wcnt) 

where: 

buff is the array to be used to buffer the data received. The array 
must be one word larger than the message to be received 
because the first word contains the integer number of words 
actually transmitted when IRCVD is complete 

went is the maximum integer number of words that can be 
received 

Errors: 

i = Normal return. 
= 1 No such job exists in the system. (A job exists as long as it 
is loaded, whether or not it is active.) 

Example: 

INTEGER*2 MSG(<m ) 



CALL IRCyD(MSGt40) 



CALL MWAIT 

IRCVDC 

The IRCVDC function receives data and enters an assembly language com- 
pletion routine when the message is received. The IRCVDC is queued, and 
program execution stays with the issuing job. When the other job sends a 
message, the completion routine specified is queued and run according to 
standard scheduling of completion routines. 



Form: i = 
where: 

buff 



IRCVDC (buff,wcnt,crtn) 



is the array to be used to buffer the data received. The array 
must be one word larger than the message to be received be- 
cause the first word contains the integer number of words 
actually transmitted when IRCVDC is complete 
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went is the maximum integer number of words to be received 

crtn is the assembly language completion routine to be entered. 
This name must be specified in a FORTRAN EXTERNAL 
statement in the routine that issues the IRCVDC call 



Errors: 

i = Normal return. 
= 1 No such job exists in the system. (A job exists as long as it 
is loaded, whether or not it is active.) 

IRCVDF 

The IRCVDF function receives data and enters a FORTRAN completion 
subroutine when the message is received. The IRCVDF is queued, and pro- 
gram execution continues with the issuing job. When the other job sends a 
message, the FORTRAN completion routine specified is entered. 

Form: i = IRCVDF (buff,wcnt,area,crtn) 

where: 

buff is the array to be used to buffer the data received. The array 
must be one word larger than the message to be received 
because the first word contains the integer number of words 
actually transmitted when IRCVDF is complete 

went is the maximum integer number of words to be received 

area is a four-word area to be set aside for linkage information. 
This area must not be modified by the FORTRAN program 
and the USR must not swap over it. This area can be re- 
claimed by other FORTRAN completion routines when crtn 
has been entered 

crtn is the FORTRAN completion routine to be entered. This name 
must be specified in an EXTERNAL statement in the FOR- 
TRAN routine that issues the IRCVDF call 



Errors: 



Normal return. 

1 No such job exists in the system. (A job exists as long as it 
is loaded, whether or not it is active.) 



Example: 



INTEGER*Z MSG(^1 ) »AREA(4) 
EXTERNAL RMSGRT 



CALL IRCMDFCMSG »aO. AREA. RMSGRT) 



IRCVDW 

The IRCVDW function receives data and waits. This function queues a 

message request and suspends the job issuing the request until the other 



System Subroutine Description and Examples 3-35 



job sends a message. When execution of the issuing job resumes, the mes- 
sage has been received, and the first word of the buffer indicates the num- 
ber of words transmitted. 

Form: i = IRCVDW (buff, went) 

where: 

buff is the array to be used to buffer the data received. The array 
must be one word larger than the message to be received 
because the first word contains the integer number of words 
actually transmitted when IRCVDW is complete 

went is the maximum integer number of words to be received 

Errors: 

i = Normal return. 
= 1 No such job exists in the system. (A job exists as long as it 
is loaded, whether or not it is active.) 

Example: 

INTEGER*Z MSG(ai) 

IF(IRCyDW(MSG ,40) .NE.O) STOP 'UNEXPECTED ERROR' 

3.45 IREAD/IREADC/IREADF/IREADW 

The functions IREAD, IREADC, IREADF, and IREADW transfer a speci- 
fied number of words from a file into memory. These functions require a 
queue element, which should be considered when the IQSET function (Sec- 
tion 3.42) is executed. 

IREAD 

The IREAD function transfers into memory a specified number of words 
from the file associated with the indicated channel. Control returns to the 
user program immediately after the IREAD function is initiated. No special 
action is taken when the transfer is completed. 

Form: i = IREAD (wcnt,buff,blk,chan) 

where: 

went is the relative integer number of words to be transferred 
buff is the array to be used as the buffer; this array must contain 

.^4- l^^r^f..** ^i%n-mn-^ vnTr^i/'ri c^ 
CL\j ICCXDL t*/U/tt' VVU±U.i3 

blk is the integer block number of the file to be read. The first 
block of a file is block number 0. The blk argument must be 
updated when necessary. For example, if the program is read- 
ing two blocks at a time, blk should be updated by 2 

chan is the integer specification for the RT-11 channel to be used 

When the user program needs to access the data read on the specified 
channel, an IWAIT function should be issued. This makes sure that the 
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IREAD operation has been completed. If an error occurred during the trans- 
fer, the IWAIT function indicates the error. 



Errors: 



i = n Normal return; n equals the number of words requested (0 
for non-file-structured read, multiple of 256[decimal] for 
file-structured read). If the read is from a magtape, the 
number of words requested is returned. For example: 

If went is a multiple of 256 and less than that number 
of words remain in the file, n is shortened to the num- 
ber of words that remain in the file; thus, if went is 512 
and only 256 words remain, i = 256. 

If went is not a multiple of 256 and more than went 
words remain in the file, n is rounded up to the next 
block; thus, if went is 312 and more than 312 words 
remain, i = 512, but only 312 are read. 

If went is not a multiple of 256 and less than went 
words remain in the file, n equals a multiple of 256 that 
is the actual number of words being read. 

= -1 Attempt to read past end-of-file; no words remain in the file. 
= -2 Hardware error occurred on channel. 
= -3 Specified channel is not open. 

NOTE 

If an asynchronous operation on a channel (for example, 
IREAD) results in end-of-file, the following IWAIT will not 
detect it. IWAIT detects only hard error conditions. A subse- 
quent operation on that channel will detect end-of-file and 
returns to the user with the end-of-file error code. Under 
these conditions, the subsequent operation is not initiated. 



Example: 



INTEGER*2 BUFFER < 25B ) »RCODE .BLK 



RCODE = IREAD(25G. BUFFER .BLK .ICHAN) 

IF<RC0DE+1) 1010(1000.10 
C IF NO ERROR. START HERE 
10 . 



IFdWAITdCHAN) .NE.O) GOTO 1010 



1000 CONTINUE 

C END OF FILE PROCESSING 



1010 



CALL EXIT 


(NORMAL END OF PROGRAM 


STOP 'FATAL READ' 




END 





System Subroutine Description and Examples 3-37 



IREADC 

The IREADC function transfers a specified number of words from the indi- 
cated channel into memory. Control returns to the user program immedi- 
ately after the IREADC function is initiated. When the operation is com- 
plete, the specified assembly language routine (crtn) is entered as an asyn- 
chronous completion routine. 

Form: i = IREADC (wcnt,buff,blk,chan,crtn) 

where: 



went 
buff 

blk 

chan 
crtn 



is the integer number of words to be transferred 

is the array to be used as the buffer; this array must contain 
at least went words 

is the integer block number of the file to be read. The user 
program normally updates blk before it is used again. The 
first block of a file is block number 

is the integer specification for the RT-11 channel to be used 

is the assembly language routine to be activated when the 
transfer is complete. This name must be specified in an EX- 
TERNAL statement in the FORTRAN routine that issues the 
IREADC call 



Errors: 



See the errors under IREAD. 
Example: 

INTEGER*2 IBUF ( 25B ) .RCODE » IBLK 
EXTERNAL RDCMP 



RCODE= IREADC (25Bt IBUF »IBLK . I CHAN .RDCMP ) 

IREADF 

The IREADF function transfers a specified number of words from the indi- 
cated channel into memory. Control returns to the user program immedi- 
ately after the IREADF function is initiated. When the operation is com- 
plete, the specified FORTRAN subprogram (crtn) is entered as an asynchro- 
nous completion routine (see Section 1.2.1.2). 

Form: i = IREADF (wcnt,buff,blk,chan,area,crtn) 

where: 

went is the integer number of words to be transferred 

buff is the array to be used as the buffer; this array must contain 
at least went words 

blk is the integer block number of the file to be used. The user 
program normally updates blk before it is used again. The 
first block of a file is block number 
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Chan is the integer specification for the RT-11 channel to be used 

area is a four-word area to be set aside for link information; this 
area must not be modified by the FORTRAN program or 
swapped over by the USR. This area can be reclaimed by 
other FORTRAN completion functions when crtn has been 
activated 

crtn is the FORTRAN routine to be activated on completion of the 
transfer. This name must be specified in an EXTERNAL 
statement in the routine that issues the IREADF call. Section 
1.2.1.2 describes completion routines 

Errors: 

See the errors under IRE AD. 

Example: 

INTEGER*2 DBLK(a) .BUFFER(25B) .BLKNO 

DATA DBLK/3RDK0 »3RINP»3RUT (3RDAT/ ,BLKNO/0/ 

EXTERNAL RCMPLT 



ICHAN=IGETC( ) 

IFdCHAN.LT.O) STOP 'NO CHANNEL AVAILABLE' 
IF(IFETCH(DBLK) ,NE.O) STOP 'BAD FETCH' 
IF(LOOKUP( ICHAN »DBLK) .LT.O) STOP 'BAD LOOKUP' 



20 IF(IREADF(25B»BUFFER, BLKNO, ICHAN»DBLK , RCMPLT) .LT.O) GOTO 
100 

C PERFORM OVERLAP PROCESSING 



SYNCHRONIZER 

CALL IWAIT(ICHAN) !WAIT FOR COMPLETION ROUTINE TO RUN 

BLKN0=BLKN0+1 lUPDATE BLOCK NUMBER 

GOTO 20 



C END OF FILE PROCESSING 
100 CALL ICLOSE(ICHAN.I) 

I=ICLOSE( ) 

CALL IFREEC(ICHAN) 



CALL EXIT 
END 

SUBROUTINE RCMPLTd .J) 
C THIS IS THE COMPLETION ROUTINE 



RETURN 
END 
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IREADW 

The IREADW function transfers a specified number of words from the indi- 
cated channel into memory. Control returns to the user program when the 
transfer is complete or when an error is detected. 

Form: i = IREADW (wcnt,bufr,blk,chan) 



where: 



went is the integer number of words to be transferred 

buff is the array to be used as the buffer; this array must contain 
at least went words 

blk is the integer block number of the file to be read. The user 
program normally updates blk before it is used again 

chan is the integer specification for the RT-11 channel to be used 
Errors: 

See the errors under IRE AD. 
Example: 

INTEGER»2 IBUFdOZ^) 



C 
C 
C 



ICODE= IREADW (102a ,IBUF .IBLK 1 1 CHAN) 

IF(ICODE.EO.-l) GOTO 100 !END OF FILE PROCESSING AT 100 

IF( ICODE.LT.-l) GOTO 200 ! ERROR PROCESSING AT 200 

MODIFY BLOCKS 



WRITE THEM OUT 

ICODE=IWRITW( 102/^ .IBUF .IBLK . I CHAN) 



3o48 IRENAiyi 



The IRENAM function causes an immediate change of the name of a speci- 
fied file. 

Form: i = IRENAM (chan,dblk) 



where: 



chan is the integer specification for the RT-ii channel to ue useu 
for the operation. You must obtain this channel through an 
IGETC call, or you can use channel 16(decimal) or higher if 
you have done an ICDFN call. The channel is again available 
for use once the rename operation is completed 

dblk is the eight- word area specifying the name of the existing file 
and the new name to be assigned. If considered as an eight- 
element INTEGER*2 array, dblk has the form: 
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Words 1-4 specify the Radix-50 file descriptor for the old 
file name 

Words 5-8 specify the Radix-50 file descriptor for the 
new file name 

NOTE 

The arguments of IRENAM must be positioned so that the 
USR does not swap over them. 

If a file already exists with the same name as the new file on the indicated 
device, it is deleted. IRENAM requires that the handler to be used be resi- 
dent at the time the IRENAM is issued. If it is not, a monitor error occurs. 
The device names specified in the file descriptors must be the same. 

For more information on renaming files, see the .RENAME programmed 
request (Section 2.75). 



Errors: 



Normal return. 

1 Specified channel is already open. 

2 Specified file was not found. 

3 A file by that name already exists and is protected. 



Example: 



REAL«8 NAME(2) 

DATA NAME/12RDK0FTN2 



DAT ,12RDK0FTN2 OLD/ 



ICHAN=IGETC( ) 
IF( ICHAN.LT.O) STOP 'NO 
CALL IRENAM(ICHAN»NAME) 
CALL IFREEC( ICHAN) 



CHANNEL' 

IPRESERME 



OLD DATA FILE 



3.47 IREOPN 



The IREOPN function reassociates a specified channel with a file on which 
an ISAVES was performed. The ISAVES/IREOPN combination is useful 
when a large number of files must be operated on at one time. Necessary 
files can be opened with LOOKUP and their status preserved with 
ISAVES. When data is required from a file, an IREOPN enables the pro- 
gram to read from the file. The IREOPN need not be done on the same 
channel as the original LOOKUP and ISAVES. 

Form: i = IREOPN (chan,cblk) 

where: 

chan is the integer specification for the RT-11 channel to be asso- 
ciated with the reopened file; this channel must be initially 
inactive 
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cblk is the five-word block where the channel status information 
was stored by a previous ISAVES. This block, considered as a 
five-element INTEGER*2 array, has the following format: 

Word 1 Channel status word. 

2 Starting block number of the file; zero for non- 
file-structured devices. 

3 Length of file (in 256-word blocks). 

4 Reserved for future use. 

5 Two information bytes. Even byte: I/O count of 
the number of requests outstanding on this chan- 
nel. Odd byte: unit number of the device associ- 
ated with the channel. 



Errors: 



Example: 



Normal return. 

1 Specified channel is already in use. 



INTEGER»2 SAMES(5.10) 
DATA ISVPTR/1/ 



CALL ISAVES( ICHAN .SAMES( 1 tISUPTR) ) 



CALL IREOPNdCHAN.SAUESd »ISyPTR) ) 



3.48 ISAVES 



The ISAVES function stores five words of channel status information into a 
user-specified array. These words contain all the information that RT-11 
requires to completely define a file. When an ISAVES is finished, the data 
words are placed in memory and the specified channel is closed, so that it is 
again available for use. When the saved channel data is required, the IRE- 
OPN function (Section 3.47) is used. 

ISAVES can be used only if a file was opened with a LOOKUP call (see 
Section 3.79). If lENTER was used, ISAVES returns an error. Note that 
ISAVES is not legal on magtape or cassette files. 



Form: 



ISAVES (chan,cblk) 



chan is the integer specification for the RT-11 channel whose 
status is to be saved. You must obtain this channel through 
an IGETC call, or you can use channel 16 or higher if you 
have done an ICDFN call 

cblk is a five-word block in which the channel status information 
describing the open file is stored (see Section 3.47 for the 
format of this block). 
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The ISAVES/IREOPN combination is very useful, but care must be ex- 
ercised when using it. In particular, the following cases should be avoided. 

') 

1. If an ISAVES is performed on a file and the same file is then 

deleted before it is reopened, the space occupied by the file be- 
comes available as an empty space which could then be used by 
the lENTER function. If this sequence occurs, there is a change in 
the contents of the file whose status was supposedly saved. 

2. Although the handler for the required peripheral need not be in 
memory for execution of an IREOPN, a fatal error is generated if 
the handler is not in memory when an IREAD or IWRITE is 
executed. 

Errors: 

i = Normal return. 

= 1 The specified channel is not currently associated with any 

^ file. 

^ = 2 The file was opened with an lENTER call. 

Example: 

INTEGER*2 BLK(5) 



IFdSAyESdCHAN tBLK) .NE.O) STOP 'ISAVES ERROR' 



3.49 ISCHED 



The ISCHED function schedules a specified FORTRAN subroutine to be 
run as an asynchronous completion routine at a specified time of day. Sup- 
port for ISCHED in SJ requires timer support. 

Form: i = ISCHED (hrs,min,sec,tick,area,id,crtn) 

where: 

hrs is the integer number of hours 

min is the integer number of minutes 

sec is the integer number of seconds 

tick is the integer number of ticks (1/60 of a second on 60-cycle 
clocks; 1/50 of a second on 50-cycie clocks) 

area is a four-word area that must be provided for link informa- 
tion; this area must never be modified by the FORTRAN pro- 
gram, and the USR must not swap over it. This area can be 
reclaimed by other FORTRAN completion functions when 
crtn has been activated 

id is the identification integer to be passed to the routine being 

scheduled 
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crtn is the name of the FORTRAN subroutine to be entered at the 
time of day specified. This name must be specified in an EX- 
TERNAL statement in the FORTRAN routine that issues the 
ISCHED call. The subroutine has one argument. For exam- 
ple: 

SUBROUTINE crtn(id) 
INTEGER id 

When the routine is entered, the value of the integer argu- 
ment is the value specified for id in the appropriate ISCHED 
call 

Notes: 

1. The scheduling request made by ISCHED can be canceled at a later 
time by an ICMKT function call. 

2. If the system is busy, the actual time of day that the completion routine 
is run may be later than the requested time of day. 

3. A FORTRAN subroutine can periodically reschedule itself by issuing 
its own ISCHED or ITIMER calls from within the routine. 

4. ISCHED requires a queue element; this should be considered when the 
IQSET function (Section 3.42) is executed. 

Errors: 

i = Normal return. 
= 1 No queue elements available; unable to schedule request. 

Example: 

INTEGER*Z LINK(il) (LINKAGE AREA 

EXTERNAL NOON ! NAME OF ROUTINE TO RUN 



I = ISCHED( 12 .0 »0 tO tLINK »0 (NOON) ! RUN SUBR NOON AT 12 PM 

t 

* (rest of main program) 

* 

END 

SUBROUTINE NOON(ID) 
C 

C THIS ROUTINE WILL TERMINATE EXECUTION AT LUNCHTIME* 
C IF THE JOB HAS NOT COMPLETED BY THAT TIME. 
C 

STOP 'ABORT JOB -- LUNCHTIME' 

END 

3.50 ISCOMP 

(See SYSLIB subroutine SCOMP.) 

3.51 ISDAT/ISDATC/ISDATF/ISDATW (FB and KM ©nly) 

The functions ISDAT, ISDATC, ISDATF, and ISDATW are used with the 
IRCVD, IRCVDC, IRCVDF, and IRCVDW calls to allow message transfers 
under the FB or XM monitor. Note that the buffer containing the message 

3-44 System Subroutine Description and Examples 



should not be modified or reused until the message has been received by the 
other job. These functions require a queue element, which should be consid- 
) ered when the IQSET function (see Section 3.42) is executed. 

ISDAT 

The ISDAT function transfers a specified number of words from one job to 
the other. Control returns to the user program immediately after the trans- 
fer is queued. This call is used with the MWAIT routine (see Section 3.90). 

Form: i = ISDAT (buff, went) 

where: 

buff is the array containing the data to be transferred 

went is the integer number of data words to be transferred 
Errors: 

i = Normal return. 
\ = 1 No such job currently exists in the system. (A job exists as 

long as it is loadable, whether or not it is active.) 



Example: 



INTEGER*2 MSG(40) 



CALL ISDAT(MSG .aO) 



CALL MWAIT 

PUT NEW MESSAGE IN BUFFER 



ISDATC 

The ISDATC function transfers a specified number of words from one job to 
another. Control returns to the user program immediately after the trans- 
fer is queued. When the other job accepts the message through a receive 
data request, the specified assembly language routine (crtn) is activated as 
an asynchronous completion routine. 

Form: i = ISDATC (buff,wcnt,crtn) 

where: 

buff is the array containing the data to be transferred 

went is the integer number of data words to be transferred 

crtn is the name of an assembly language routine to be activated 
on completion of the transfer. This name must be specified in 
an EXTERNAL statement in the FORTRAN routine that is- 
sues the ISDATC call 



Errors: 



i = Normal return. 
= 1 No such job currently exists in the system. (A job exists as 
long as it is loaded, whether or not it is active.) 
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Example: 



INTEGER*2 MSG(^O) 
EXTERNAL RTN 



CALL ISDATC(MSG .aO.RTN) 



ISDATF 

The ISDATF function transfers a specified number of words from one job to 
the other. Control returns to the user program immediately after the trans- 
fer is queued and execution continues. When the other job accepts the mes- 
sage through a receive data request, the specified FORTRAN subprogram 
(crtn) is activated as an asynchronous completion routine (see Section 
1.2.1.2). 

Form: i = ISDATF (buff,wcnt,area,crtn) 

where: 

buff is the array containing the data to be transferred 

went is the integer number of data words to be transferred 

area is a four-word area to be set aside for link information; this 
area must not be modified by the FORTRAN program and the 
USR must not swap over it. This area can be reclaimed by 
other FORTRAN completion functions when crtn has been 
activated 

crtn is the name of a FORTRAN routine to be activated on comple- 
tion of the transfer. This name must be specified in an EX- 
TERNAL statement in the FORTRAN routine that issues the 
ISDATF call 



Errors: 



= Normal return. 

= 1 No such job currently exists in the system. (A job exists as 
long as it is loaded, whether or not it is active.) 



Example: 



INTEGER*2 MSG ( 40 ) .SPOT ( a ) 
EXTERNAL RTN 



CALL ISDATF(MSG.40 .SPOT .RTN) 



ISDATW 

The ISDATW function transfers a specified number of words from one job to 
the other. Control returns to the user program when the other job has 
accepted the data through a receive data request. 

Form: i = ISDATW (buff,wcnt) 
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\ 



where: 

buff is the array containing the data to be transferred 
went is the integer number of data words to be transferred 

Errors: 

i = Normal return. 
= 1 No such job exists in the system. (A job exists as long as it is 
loaded, whether or not it is active.) 

Example: 

INTEGER*2 MSG(^O) 

* 

4 
4 

IF (ISDATW(MSG»aO) .NE,0) STOP 'FOREGROUND JOB NOT RUNNING' 

3.52 fSDTTM 

The ISDTTM function sets the system date and time. An argument of -1 
leaves the corresponding value unchanged. 

Form: CALL ISDTTM (date,hitime,lotime) 
where: 

date is the new system date 

hitime is the high-order time of day, in ticks past midnight 

lotime is the low-order time of day, in ticks past midnight 
Example: 



C DEFINE NEW SYSTEM DATE BUT LEAME TIME UNCHANGED 
IDATE = IM0NTH*1024+IDAY*32+( IYEAR-ig72) 
CALL ISDTTM (IDATEt -1 , -1) 



3.53 ISFDAT 



The ISFDAT function allows user programs to modify the creation date of 

an RT— 1 1 filft. TVir Hfivinp mnsf Vinvo nn T?T_1 1 fi\a nf».ii^+ii>.o 

Form: i = ISFDAT (chan,dblk,idate) 
where: 

chan is the integer value of the RT-11 channel to be used for the 
operation. You must obtain this channel through an IGETC 
call, or you can use channel 16(decimal) or higher if you have 
done an ICDFN call 
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dblk 

idate 
Errors: 



1 = 




= 1 
= 2 
= 3 



is the four word RT-11 file specification, in Radix-50, of the 
file whose date is being changed 

is the integer date in RT-11 date format 



Normal return. 
Channel in use. 
File not found. 
Invalid operation. 



Example: 



This example changes the date of the file DY1:0LD23.DAT to July 4, 
1976. 

REAL»4 FILNAM(2) 

DATA FILNAM /6RDY10LD .BR23 DAT/ 

IDATE=7»102a + 4»32 + (197B-1972) ! JULY 4. 1976 

ICHAN = IGETCO ! ALLOCATE CHANNEL 

I = ISFDAT(ICHAN»FILNAM. IDATE) !SET THE DATE 

IF (I.NE.O) STOP 'ERROR DURING ISFDAT CALL' 



END 



^■O^ I '^ i™ id i™ a 



The ISLEEP function suspends the main program execution of a job for a 
specified amount of time. The specified time is the sum of hours, minutes, 
seconds, and ticks specified in the ISLEEP call. All completion routines 
continue to execute. 



Form: i = 
where: 

hrs 
min 
sec 
tick 

Notes: 



ISLEEP (hrs,min,sec,tick) 

is the integer number of hours 

is the integer number of minutes 

is the integer number of seconds 

is the integer number of ticks (1/60 of a second on 60-cycle 
clocks; 1/50 of a second on 50-cycle clocks) 



1. SLEEP requires a queue element, which should be considered when the 
IQSET function (Section 3.42) is executed. 

2. If the system is busy, the time for which execution is suspended may be 
longer than that specified. 

Errors: 

i = Normal return. 
= 1 No queue element available. 
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Example: 



CALL lOSEKZ) 

t 
« 

* 

CALL ISLEEP(0.0,0,4) IGIVE BACKGROUND JOB SOME TIME 

3.55 ISPFN/ISPFNC/ISPFNF/ISPFNW 

The functions ISPFN, ISPFNC, ISPFNF, and ISPFNW are used in conjunc- 
tion with special functions to various handlers. They provide a means of 
doing device-dependent functions, such as rewind and backspace, to those 
devices. If ISPFN function calls are made to any other devices, the function 
call is ignored. For more information on programming for specific devices, 
see the RT—11 Software Support Manual. 

To use these functions, the handler must be in memory, and a channel must 
be associated with a file via a non-file-structured LOOKUP call. These 
functions require a queue element; this should be considered when the 
IQSET function (Section 3.42) is executed. 

ISPFN 

The ISPFN function queues the specified operation and immediately re- 
turns control to the user program. The IWAIT function can be used to 
ensure completion of the operation. 

Form: i = ISPFN (code,chan[,wcnt,buff,blk]) 

where: 

code is the integer numeric code of the function to be performed 
(see Table 3-1) 

chan is the integer specification for the RT-11 channel to be used 
for the operation. You must obtain this channel through an 
IGETC call, or you can use channel 16(decimal) or higher if 
you have done an ICDFN call 

went is the integer number of data words in the operation. This 
parameter is optional with some ISPFN calls, depending on 
the particular function. Default value is 0. In magtape opera- 
tions, it specifies the number of records to space forward or 
backward. For a backspace operation {wcnt = Q), the tape drive 
backspaces to a tape mark or to the beginning-of-tape. For a 
forward space operation {wcnt=Qi), the tape drive forward 
spaces to a tape mark or the end-of-tape 

buff is the array to be used as the data buffer. This parameter is 
optional with some ISPFN calls, depending on the particular 
function. Default value is 
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blk is the integer block number of the file to be operated upon. 
This parameter is optional with some ISPFN calls, depending 
on the particular function. Default value is 

When this argument is supplied by magtape, it is the address 
of a four-word error and status block used for returning the 
exception conditions. The four words must be initialized to 
zero. 

The error and status block must always be mapped when run- 
ning in the XM monitor, and the USR must not swap over it. 
To obtain the address of the error block, execute the following 
instructions: 

INTEGER*2 ERRftDR . ERRBLK ( ^ ) 
DflTft ERRBLK /O ,0 .0 lO ./ 



ERRADR = lADDR (ERRBLK) ! GET THE ADDRESS OF THE a-WORD ERROR BLOCK 
ICODE = ISPFN (CODE iICHAN iWDCT iBUF lERRADR) 

The three optional arguments {went, buff, blk) are not individually op- 
tional. You must have all or none present. 



Table 3-1: Functions and Function Codes (Octal) 

Function MS.MT.MM CT DX DM DY Dl, LD DU DW DZ 

Read absolute 377 377 377 377 377* 377* 

Write absolute 376 376 376 376 376* 376* 

Write absolute with 

deleted data 375 375 

Forward to last file 377 

Forward to last block 376 

Forward to next file 375 

Forward to next block 374 

Rewind to load point 373 373 

Write file gap 372 

Write end-of-fi!e 377 

Forward 1 block 376 

Backspace 1 block 375 

Initialize the bad 

block replacement table 374 374 

Write with extended 

record gap 374 

Offline 372 

Return volume size 373 373 373 373 373 373<- 

Read/write translation table 372 372 

Write variable size blocks 37 1 

Direct MSCP access 371 

Read variable size blocks 370 

Stream at 100 ips 

(MS only) 367 

' When using special functions .')76 and 377 with DW or DZ: 

went is the track to be read of written. 

blk is the sector. 

buf is the address of a 256-word buffer. 

Special functions 376 and 377 with DZ handler do not interleave sectors. RX50 diskettes, 
handled by DZ, have 80 tracks. Special functions 376 and 377 wrap to track after track 79. 

* When using special function 373 with DW: 

chan is the channel on which DW was opened with .LOOKUP. 

buf is the address of a one-word Imffer in which the size of the volume will be 

returned: 9727(decimal) block.s for an RO.W, 19519(defimal) blocks for an 

RD51. 
blk is not used and should be .set to 0. 
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Errors: 



Normal return. 

1 Attempt to read or write past end-of-file. 

2 Hardware error occurred on channel. 

3 Channel specified is not open. 



Example: 



CALL ISPFN( "373 .ICHAN) 



IREWIND 



ISPFNC 

The ISPFNC function queues the specified operation and immediately re- 
turns control to the user program. When the operation is complete, the 
specified assembly language routine {crtn) is entered as an asynchronous 
completion routine. 

Form: i = ISPFNC (code,chan,wcnt,buff,blk,crtn) 



where: 



code is the integer numeric code of the function to be performed 
(see Table 3-1) 

chan is the integer specification for the RT-11 channel to be used 
for the operation. You must obtain this channel through an 
IGETC call, or you can use channel 16(decimal) or higher if 
you have done an ICDFN call 

went is the integer number of data words in the operation; the de- 
fault value for this argument is 

buff is the array to be used as the data buffer; the default value for 
this argument is 

blk is the integer block number of the file to be operated upon; 
this argument must be if not required 

When this argument is supplied by magtape, it is the address 
of a four-word error and status block used for returning the 
exception conditions. The four words must be initialized to 0. 

The error and status block must always be mapped when run- 
ning in the XM monitor, and the USR must not swap over it. 
To obtain the address of the error block execute the following 
instructions: 



INTEGER*2 
DATA ERRBLK 



ERRADR . ERRBLK (^) 
/ 1 1 1 » / 



!GET ADDRESS OF 4-WORD ERROR BLOCK 

ERRADR = lADDR (ERRBLK) 

ICODE = ISPFNC (CODE .ICHAIM .WDCT »BUF tERRADR) 
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crtn is the name of an assembly language routine to be activated 
on completion of the operation. This name must be specified 
in an EXTERNAL statement in the FORTRAN routine that 
issues the ISPFNC call 

Errors: 

i = Normal return. 

= 1 Attempt to read or write past end-of-file. 

= 2 Hardware error occurred on channel. 

= 3 Channel specified is not open. 

Example: 

EXTERNAL SFCDMP ! NAME OF ASSEMBLY LANGUAGE COMPLETION RTN 

» 

ICODE = ISPFNC(CODE .ICHAN iWDCT »BUF »BLK (SFCOMP) 

ISPFNF 

The ISPFNF function queues the specified operation and immediately re- 
turns control to the user program. When the operation is complete, the 
specified FORTRAN subprogram {crtn) is entered as an asynchronous com- 
pletion routine. 

Form: i = ISPFNF (code,chan,wcnt,buff,blk,area,crtn) 

where: 

code is the integer numeric code of the function to be performed 
(see Table 3-1) 

chan is the integer specification for the RT-11 channel to be used 
for the operation. You must obtain this channel through an 
IGETC call, or you can use channel 16(decimal) or higher if 
you have done an ICDFN call 

went is the integer number of data words in the operation; this 
argument must be if not required 

buff is the array to be used as the data buffer; this argument must 
be if not required 

blk is the integer block number of the file to be operated upon; 
this argument must be if not required 

When this argument is supplied by magtape, it is the address 
of a four-word error and status block used for returning the 
exception conditions. The four words must be initialized to 0. 

The error and status block must always be mapped when 
running in the XM monitor, and the USR must not swap over 
it. To obtain the address of the error block, execute the fol- 
lowing instructions: 
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INTEGER#2 
DATA ERRBLK 



ERRADR , ERRBLK (4) 
/ ) 1 1 f / 



area 



crtn 



Errors: 



= 

= 1 

= 2 

= 3 



Example: 



!GET THE ADDRESS OF THE 4-WDRD ERROR BLOCK 

ERRADR = lADDR (ERRBLK) 

ICODE = ISPFNF (CODE »ICHAN.WDCT»BUF, ERRADR) 

is a four-word area to be set aside for linkage information; 
this area must not be modified by the FORTRAN program, 
and the USR must not swap over it. This area can be re- 
claimed by other FORTRAN completion functions when crtn 
has been activated 

is the name of a FORTRAN routine to be activated on com- 
pletion of the operation. This name must be specified in an 
EXTERNAL statement in the FORTRAN routine that issues 
the ISPFNF call (Section 1.2.1.2 describes completion 
routines) 



Normal return. 

Attempt to read or write past end-of-file. 
Hardware error occurred on channel. 
Channel specified is not open. 



REAL#4 MTNAME(2) .AREAC 
DATA MTNAME/3RMT0 ,0./ 
EXTERNAL DONSUB 



I = IGETC( ) 

CALL IFETCH(MTNAME) 
CALL LOOKUP( I tMTNAME) 
IERR=ISPFNF( "373 ,1 tO »0 



! ALLOCATE CHANNEL 
IFETCH MT HANDLER 
INON-FILE-STRUCTURED LOOKUP ON 
O.AREA fDONSUB) (REWIND MAGTAPE 



MTO 



END 

SUBROUTINE DONSUB 

RUNS WHEN MTO HAS BEEN REWOUND 



END 



ISPFNW 

The ISPFNW function queues the specified operation and returns control to 

the user program when the operation is complete. 

Form: i = ISPFNW (code,chan[,wcnt,buff,blk]) 
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where: 



code is the integer numeric code of the function to be performed 
(see Table 3-1) 

chan is the integer specification for the RT-11 channel to be used 
for the operation. You must obtain this channel through an 
IGETC call, or you can use channel 16(decimal) or higher if 
you have done an ICDFN call 

went is the integer number of data words in the operation. This 
parameter is optional with some ISPFNW calls, depending on 
the function 

buff is the array to be used as the data buffer. This parameter is 
optional with some ISPFNW calls, depending on the function 

blk is the integer block number of the file to be operated upon. 
This parameter is optional with some ISPFNW calls, depend- 
ing on the function 

When this argument is supplied by magtape, it is the address 
of a four-word error and status block used for returning the 
exception conditions. The four words must be initialized to 0. 

The error and status block must always be mapped when 
running in the XM monitor, and the USR must not swap over 
it. To obtain the address of the error block execute the follow- 
ing instructions: 

IIMTEGER#2 ERRADR . ERRBLK ( a ) 
DATA ERRBLK /O »0 .0 .0 ./ 



!GET THE ADDRESS OF THE 4-Ia|0RD ERROR BLOCK 

ERRADR = IADDR (ERRBLK) 

ICODE = ISPFN (CODE tICHANtWDCT (BUF .ERRADR) 



Errors: 



i = Normal return. 

= 1 Attempt to read or write past end-of-file. 

= 2 Hardware error occurred on channel. 

= 3 Channel specified is not open. 



Example: 



INTEGER*2 BUF(B5) (TRACK .SECTOR .DBLK(4) 
DATA DBLK/3RDX0 .0 .0 .0/ 



ICHAN=IGETC( ) 

IF(ICHAN.LT.O) STOP 'NO CHANNEL AVAILABLE' 

IF(LOOKUP( ICHAN .DBLK) .LT.O) STOP 'BAD LOOKUP' 



READ AN ABSOLUTE TRACK AND SECTOR FROM THE FLOPPY 
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ICODE=ISPFNW( "377 .ICHAIM tTRACK »BUF .SECTOR) 

BUF(l) IS THE DELETED DATA FLAG 
BUF(2-B5) IS THE DATA 



3.56 ISPY 



The ISPY function returns the integer value of the word at a specified offset 
from the RT-11 resident monitor. This subroutine uses the .GVAL pro- 
grammed request to return fixed monitor offsets. (See the RT-11 Software 
Support Manual for information on fixed offset references.) 

Form: i = ISPY (ioff) 

where: 

ioff is the offset (from the base of RMON) to be examined 

Function Result: 

The function result (i) is set to the value of the word examined. 

Example: 



c 
c 
c 

c 
c 
c 



BRANCH TO 200 IF RUNNING UNDER FB MONITOR 

IF (ISPY ( "300) .AND. 1 ) GOTO 200 

WORD AT OCTAL 300 FROM RMON IS 
THE CONFIGURATION WORD. 



3.57 ITIMER 



The ITIMER function schedules a specified FORTRAN subroutine to be run 
as an asynchronous completion routine after a specified time interval has 
elapsed. This request is supported by SJ when the timer support special 
feature is included during system generation. 

Form: i = ITIMER (hrs,min,sec,tick,area,id,crtn) 

where: 

hrs is the integer number of hours 

min is the integer number of minutes 

sec is the integer number of seconds 

tick is the integer number of ticks (1/60 of a second on 60-cycle 
clocks; 1/50 of a second on 50-cycle clocks) 

area is a four-word area that must be provided for link informa- 
tion; this area must never be modified by the FORTRAN pro- 
gram, and the USR must never swap over it. This area can be 
reclaimed by other FORTRAN completion functions when 
crtn has been activated 

id is the identification integer to be passed to the routine being 

scheduled 

crtn is the name of the FORTRAN subroutine to be entered when 
the specified time interval elapses. This name must be speci- 
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fied in an EXTERNAL statement in the FORTRAN routine 
that references ITIMER. The subroutine has one argument. 
For example: 

SUBROUTINE crtn(id) 
INTEGER id 

When the routine is entered, the value of the integer argu- 
ment is the value specified for id in the appropriate ITIMER 
call 

Notes: 

1. This function can be canceled at a later time by an ICMKT function 
call. 

2. If the system is busy, the actual time interval after which the comple- 
tion routine is run can be longer than the time interval requested. 

3. FORTRAN subroutines can periodically reschedule themselves by issu- 
ing ISCHED or ITIMER calls. 

4. ITIMER requires a queue element, which should be considered when 
the IQSET function (Section 3.42) is executed. 

For more information on scheduling completion routines, see Section 
1.2.1.2 and the .MRKT programmed request, Section 2.49. 



Errors: 



Example: 



Normal return. 

1 No queue elements available; unable to schedule request. 



INTEGER#2 AREA(4) 
EXTERNAL NATCHD 



C IF THE CODE FOLLOWING ITIMER DOES NOT REACH THE ICMKT CALL 
C IN 12 MINUTES* WATCH DOG COMPLETION ROUTINE WILL BE 
C ENTERED WITH ID OF 3 
C 

CALL ITIMER(0 »12 »0 .0 .AREA .3 .WATCHD) 



CALL ICMKTO (AREA! 



END 

SUBROUTINE WATCHDCID) 
C 
C THIS IS CALLED AFTER 12 MINUTES 



RETURN 
END 
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3.58 ITLOCK (FB and XM Only) 

The ITLOCK function is used in an FB or XM system to attempt to gain 
ownership of the USR. It is similar to LOCK (Section 3.78) in that, if suc- 
cessful, the user job returns with the USR in memory. However, if a job 
attempts to LOCK the USR while the other job is using it, the requesting 
job is suspended until the USR is free. With ITLOCK, if the USR is not 
available, control returns immediately and the lock failure is indicated. 
ITLOCK cannot be called from a completion or interrupt routine. 

Form: i = ITLOCKO 

For further information on gaining ownership of the USR, see the .TLOCK 
programmed request (Section 2.93). 

Errors: 

i = Normal return. 
= 1 USR is already in use. 

Example: 

IF( ITLDCK { ) .NE.O) GOTO 100 ! GOTO 100 IF USR BUSY 

3.59 ITTINR 

The ITTINR function transfers a character from the console terminal to the 
user program. If no characters are available, system action is determined 
by the setting of bit 6 of the Job Status Word. 

Form: i = ITTINRO 

If the function result (i) is less than when execution of the ITTINR func- 
tion is complete, it indicates that no character was available. Under the FB 
or XM monitor, ITTINR does not return a result of less than zero unless bit 
6 of the Job Status Word was on when the request was issued. 

There are two modes of doing console terminal input, and they are gov- 
erned by bit 12 of the Job Status Word (JSW). The JSW is at octal location 
44. If bit 12 is 0, normal I/O is performed under the following conditions: 

1. The monitor echoes all characters typed. 

2. CTRL/U and RUBOUT perform line deletion and character dele- 
tion, respectively. 

3. A carriage return, line feed, CTRL/Z, or CTRL/C must be struck 
before characters on the current line are available to the pro- 

giSiii. Wiicii uiic ui LiieSc iS typeu, i;iiciitn;i/eiS uii Lue iixie lypeu ait; 

passed one by one to the user program. 

If the console is in special mode (bit 12 set to 1), the following conditions 
apply: 

1. The monitor does not echo characters typed except for CTRL/C 
and CTRL/0. 

2. CTRL/U and RUBOUT do not perform special functions. 
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3. Characters are immediately available to the program. 

4. No ALTMODE conversion is done. 

In special mode, the user program must echo the characters desired. How- 
ever, CTRL/C and CTRL/0 are acted on by the monitor in the usual way. 

Bit 12 in the JSW must be set by the user program if special console mode 
is desired. Bit 14 in the JSW must be set if lowercase characters are de- 
sired. These bits are cleared when control returns to RT-11. 

Regardless of the setting of bit 12, when a carriage return is entered, both 
carriage return and line feed characters are passed to the program; if bit 12 
is 0, these characters will be echoed. 

Lowercase conversion is determined by the setting of bit 14. If bit 14 is 0, 
lowercase characters are converted to uppercase before being echoed (if bit 
12 is 0) and passed to a program; if bit 14 is 1, lowercase characters are 
echoed (if bit 12 is 0) and passed as received. Bit 14 is cleared when the 
program terminates. 

NOTE 

To set and/or clear bits in the JSW, do an IPEEK and then an 
IPOKE (see example under IPOKE). In special terminal 
mode (JSW bit 12 set), normal FORTRAN formatted I/O from 
the console is undefined. 

If the single-line editor has been enabled with the SET SL ON and SET SL 
TTYIN commands, input from an ITTINR request can be edited by the 
single-Hne editor if JSW bits 4 and 12 are 0. However, if either bit 4 or bit 
12 is set, SL will not edit ITTINR input. If SL is editing input, the state of 
bit 6 (inhibit TT wait) is ignored and an ITTINR request will not return 
until an edited line is available. 

In the FB or XM monitor, CTRL/F and CTRL/B (and CTRL/X in monitors 
with the system job feature) are not affected by the setting of bit 12. The 
monitor always acts on these characters if the SET TT FB command is in 
effect. 

Also under the FB or XM monitor, if a terminal input request is made and 
no character is available, job execution is normally suspended until a char- 
acter is ready. If a program requires execution to continue and ITTINR to 
return a result of less than zero, it must turn on bit 6 of the JSW before the 
ITTINR. Bit 6 is cleared when a program terminates. The results of 
ITTINR must be stored in an INTEGER type variable for the purposes of 
error checking. Once it is known that the call did not have an error return, 
the result can be moved into a LOGICAL* 1 variable or array element. 
Direct placement into a LOGICAL* 1 variable will lead to incorrect results, 
because the negative flag (bit 15 set) is lost in conversion to a L0GICAL*1 
variable. 

Function Results: 

i >0 Character read. 
<0 No character available. 
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Example: 



I ICHAR=ITTINR( ) ! READ A CHARACTER FROM THE CONSOLE 

IF(ICHAR.LT.O) GOTO 100 ! CHARACTER NOT AVA ILABLE 

3.60 ITTOUR 

The ITTOUR function transfers a character from the user program to the 
console terminal if there is room for the character in the monitor buffer. If 
it is not currently possible to output a character, an error flag is returned. 

Form: i = ITTOUR (char) 

where: 

char is the character to be output, right-justified in the integer 
(can be LOGICAL*! entity if desired) 

If the function result (i) is 1 when execution of the ITTOUR function is 
complete, it indicates that there is no room in the buffer and that no charac- 
) ter was output. Under the FB or XM monitor, ITTOUR normally does not 

return a result of 1. Instead, the job is blocked until room is available in the 
output buffer. If a job requires execution to continue and a result of 1 to be 
returned, it must turn on bit 6 of the JSW (location 44) before issuing the 
request. 

NOTE 

If a foreground job has characters in the TT output buffer, 
j they are not output under the following conditions: 

1. If a background job is doing output to the console TT, the 
foreground job cannot output characters from its buffer 
until the background job outputs a line feed character. 
This can be troublesome if the console device is a graph- 
ics terminal and the background job is doing graphic out- 
put without sending any line feeds. 

2. If no background job is running (that is, KMON is in 
control of background), the foreground job cannot output 
its characters until the user types a carriage return or a 
line feed. In the former case, KMON gets control again 
and locks out foreground output as soon as the fore- 
ground output buffer is empty. 

Note that the use of PRINT eliminates these problems. 

Function Results: 



Character was output. 

1 Ring buffer is full. 



Example: 



DO 20 1=1 »5 
10 IF(ITTOUR( "007) .NE.O) GOTO 10 ! R I NG BELL 5 T IMES 
20 CONTINUE 
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3.61 ITWAIT (SYSGEN Option In SJ) 

The ITWAIT function suspends the main program execution of the current 
job for a specified time interval. All completion routines continue to exe- 
cute. 

Form: i = ITWAIT (itime) 

where: 

itime is the two-word internal format time interval 

itime (1) is the high-order time 
itime (2) is the low-order time 

Notes: 

1. WAIT requires a queue element, which should be considered when the 
IQSET function (Section 3.42) is executed. 

2. If the system is busy, the actual time interval during which execution is 
suspended may be longer than the time interval specified. 

Errors: 

i = Normal return. 
= 1 No queue element available. 

Example: 

INTEGER*2 TIME(2) 

* 
t 

CALL ITWAIT(TIME) IWAIT FOR TIME 

3.62 lUNTIL (SYSGEN Option in SJ) 

The lUNTIL function suspends main program execution of the job until the 
time of day specified. All completion routines continue to run. 

Form: i = lUNTIL (hrs,min,sec,tick) 

where: 

hrs is the integer number of hours 

mm is uiic integer num»jer Ox minuuGS 

sec is the integer number of seconds 

tick is the integer number of ticks (1/60 of a second on 60-cycle 
clocks; 1/50 of a second on 50-cycle clocks) 

Notes: 

1. lUNTIL requires a queue element, which should be considered when 
the IQSET function (Section 3.39) is executed. 
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2. If the system is busy, the actual time of day that the program resumes 
execution may be later than that requested. 

Errors: 

i = Normal return. 
= 1 No queue element available. 

Example: 

C TAKE A LUNCH BREAK 

CALL lUNTILC 13 tO .0 »0) ISTART UP AGAIN AT 1 P.M. 

3.63 IVERIF 

See SYSLIB subroutine VERIFY, Section 3.113. 

3.64 IWAIT 

The IWAIT function suspends execution of the main program until all 
input/output operations on the specified channel are complete. This func- 
tion is used with IREAD, IWRITE, and ISPFN calls. Completion routines 
continue to execute. 

Form: i = IWAIT (chan) 
where: 

chan is the integer specification for the RT-11 channel to be used. 
You must obtain this channel through an IGETC call, or you 
can use channel 16(decimal) or higher if you have done an 
ICDFN call 

For further information on suspending execution of the main program, see 
the .WAIT programmed request (Section 2.101). 

Errors: 

i = Normal return. 
= 1 Channel specified is not open. 

= 2 Hardware error occurred during the previous I/O operation 
on this channel. 

Example: 

IF( INAIT( ICHAN) .NE.O) CALL I0ERR(4) 

3.65 IWRITE/IWRITC/IWRITF/IWRITW 

The functions IWRITE, IWRITC, IWRITF, and IWRITW transfer a speci- 
fied number of words from memory to the specified channel. The IWRITE 
functions require queue elements; this should be considered when the 
IQSET function (Section 3.42) is executed. 

IWRITE 

The IWRITE function transfers a specified number of words from memory 

to the specified channel. Control returns to the user program immediately 
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after the request is queued. No special action is taken upon completion of 
the operation. 



Form: i = 
where: 

went 

buff 

blk 

chan 



Errors: 



IWRITE (wcnt,buff,blk,chan) 

is the integer number of words to be transferred 

is the array to be used as the output buffer 

is the integer block number of the file to be written. The user 
program normally updates hlk before it is used again 

is the integer specification for the RT-11 channel to be used. 
You must obtain this channel through an IGETC call, or you 
can use channel 16(decimal) or higher if you have done an 
ICDFN call 



i = n Normal return; n equals the number of words written, 
rounded to a multiple of 256 (0 for non-file-structured 

writes). 

NOTE 

If the word count returned is less than that re- 
quested, an implied end-of-file has occurred al- 
though the normal return is indicated. 

= -1 Attempt to write past end-of-file; no more space is available 

in the file. 
= -2 Hardware error occurred. 
= -3 Channel specified is not open. 

Example: 

Refer to the example for IRE AD. 

IWRITC 

The IWRITC function transfers a specified number of words from memory 
to the specified channel. The request is queued and control returns to the 
user program. When the transfer is complete, the specified assembly lan- 
guage routine icrtn) is entered as an asynchronous completion routine. 



Form: 



IWRITC (wcnt,buff,blk,chan,crtn) 



where: 



went is the relative integer number of words to be transferred 

buff is the array to be used as the output buffer 

blk is the relative integer block number of the file to be written. 
The user program normally updates blk before it is used 
again (for example, if the program is writing two blocks at a 
time, blk should be updated by 2) 
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chan 



crtn 



Errors: 



is the relative integer specification for the RT-11 channel to 
be used. You must obtain this channel through an IGETC 
call, or you can use channel 16(decimal) or higher if you have 
done an ICDFN call 

is the name of the assembly language routine to be activated 
upon completion of the transfer. This name must be specified 
in an EXTERNAL statement in the FORTRAN routine that 
issues the IWRITC call 



See the errors under I WRITE. 
Example: 

INTEGER*Z IBUF(25G) 
EXTERNAL CRTN 



IC0DE=INRITC(Z5B,IBUF dBLK 1 1 CHAN »CRTN) 

IWRITF 

The IWRITF function transfers a number of words from memory to the 
specified channel. The transfer request is queued and control returns to the 
user program. When the operation is complete, the specified FORTRAN 
subprogram {crtn) is entered as an asynchronous completion routine (see 
Section 1.2.1.2). 

Form: i = IWRITF (wcnt,buff,blk,chan,area,crtn) 

where: 

went is the integer number of words to be transferred 

buff is the array to be used as the output buffer 

blk is the integer block number of the file to be written. The user 
program normally updates blk before it is used again 

chan is the integer specification for the RT-11 channel to be used. 
You must obtain this channel through an IGETC call, or you 
can use channel 16(decimal) or higher if you have done an 
ICDFN call 

area is a four-word area to be set aside for link information; this 
area must not be modified by the FORTRAN program, and 
the USR must not swap over it. This area can be reclaimed by 
other FORTRAN completion functions when crtn has been 
activated 

crtn is the name of the FORTRAN routine to be activated upon 
completion of the transfer. This name must be specified in an 
EXTERNAL statement in the FORTRAN routine that issues 
the IWRITF call (Section 1.2.1.2 describes completion 
routines) 
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Errors: 

See the errors under I WRITE. 
Example: 

Refer to the example under IREADF, Section 3.45. 

IWRITW 

The IWRITW function transfers a specified number of words from memory 
to the specified channel. Control returns to the user program when the 
transfer is complete. 

Form: i = IWRITW (wcnt,buff,blk,chan) 

where: 

went is the integer number of words to be transferred 

buff is the array to be used as the output buffer 

blk is the integer block number of the file to be written. The user 
program normally updates blk before it is used again 

chan is the integer specification for the RT-11 channel to be used. 
You must obtain this channel through an IGETC call, or you 
can use channel 16(decimal) or higher if you have done an 
ICDFN call 

Errors: 

See the errors under IWRITE. 
Example: 

Refer to the example under IREADW, Section 3.45. 

3.66 JADD 

The JADD function computes the sum of two INTEGER*4 values. 

Form: i = JADD (joprl,jopr2,jres) 

where: 

joprl is an INTEGER*4 variable 

jopr2 is an INTEGER*4 variable 

jres is an INTEGER*4 variable that receives the sum of joprl and 
jopr2 

Function Results: 

i = -1 Normal return; the result is negative. 
= Normal return; the result is zero. 

= 1 Normal return; the result is positive. 
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Errors: 

i = -2 An overflow occurred while computing the result. 
Example: 

INTEGER*^ JOPl tJDP2»JRES 

« 

t 
t 

IF( JADD( JDPl ,JOPZ tJRES) ,E0.-2) GOTO 100 
3.67 JAFIX 

The JAFIX function converts a REAL*4 value to INTEGER*4. 

Form: i = JAFIX (asrcjres) 

where: 

asrc is a REAL*4 variable, constant, or expression to be converted 
to INTEGER*4 

jres is an INTEGER*4 variable that is to contain the result of the 
conversion 

Function Results: 

i = -1 Normal return; the result is negative. 
= Normal return; the result is zero. 
= 1 Normal return; the result is positive. 

Errors: 

i = -2 An overflow occurred while computing the result. 
Example: 

INTEGER*^ JOPl 
C READ A LARGE INTEGER FROM THE TERMINAL 

ACCEPT 99 »A 
99 FORMAT (F15.0) 

IF(JAFIX(A»J0P1) ,EU,-2) GOTO 100 



3.88 JCMP 



The JCMP function compares two INTEGER*4 values and returns an IN- 
TEGER*2 value that reflects the signed comparison result. 

Form: i = JCMP (joprl,jopr2) 

where: 

joprl is the INTEGER*4 variable or array element that is the first 
operand in the comparison 



System Subroutine Description and Examples 3-65 



jopr2 is the INTEGER*4 variable or array element that is the sec- 
ond operand in the comparison 

Function Results: 

i = -1 If joprl is less than7opr2. 
= If joprl is equal to jopr2. 
= 1 If joprl is greater than jopr2. 

Errors: 

None. 

Example: 

INTEGER*^ JOPXtJOPY 



IF( JCMP( JOPX »JOPY) ) 10»20t30 



3.69 JDFIX 



The JDFIX function converts a REAL*8 (DOUBLE PRECISION) value to 
INTEGER*4. 

Form: i = JDFIX (dsrcjres) 

where: 

dsrc is a REAL*8 variable, constant, or expression to be converted 
to INTEGER*4 

jres is an INTEGER*4 variable to contain the conversion result 

Function Results: 

i = -1 Normal return; the result is negative. 
= Normal return; the result is zero. 
= 1 Normal return; the result is positive. 

Errors: 

i = -2 An overflow occurred while computing the result. 
Example: 

INTEGER*^ JNUM 
REAL*8 DPNUM 



20 TYPE 9B 

98 FORMAK' ENTER POSITIVE INTEGER') 
ACCEPT 99»DPNUM 

99 FORMAT (F20.0) 

IF( JDFIX(DPNUM .JNUM) .LT.O) GOTO 20 
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3.70 JDIV 

The JDIV function computes the quotient of two INTEGER*4 values. 

Form: i = JDIV (joprl,jopr2,jres[,jrem]) 

where: 

joprl is an INTEGER*4 variable that is the dividend of the opera- 
tion 

jopr2 is an INTEGER*4 variable that is the divisor of joprl 

jres is an INTEGER*4 variable that receives the quotient of the 
operation (that is, jres = joprl /jopr2) 

jrem is an INTEGER*4 variable that receives the remainder of the 
operation. The sign is the same as that for joprl 

Function Results: 

i = -1 Normal return; the quotient is negative. 
= Normal return; the quotient is 0. 
= 1 Normal return; the quotient is positive. 

Errors: 

i = -3 An attempt was made to divide by 0. 
Example: 

INTEGER*^ JNl ,JN2 .JOUO 



CALL JDIM( JNl ,JN2 .JQUO) 



3.71 JICVT 



The JICVT function converts a specified INTEGER*2 value to INTE- 
GER*4. 

Form: i = JICVT (isrcjres) 



W7hf>rf>' 



isrc is the INTEGER*2 quantity to be converted 

jres is the INTEGER*4 variable or array element to receive the 
result 

Function Results: 

i = -1 Normal return; the result is negative. 
= Normal return; the result is 0. 
= 1 Normal return; the result is positive. 
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Errors: 

None. 
Example; 



INTEGER*^ JMAL 

CALL JICUT(478 .JMAL) ! FORM A 32-BIT CONSTANT 



3.72 JJCVT 



The JJCVT function interchanges words of an INTEGER*4 value to form 
an internal format time or vice versa. This procedure is necessary when the 
INTEGER*4 variable is to be used as an argument in a timer-support func- 
tion such as ITWAIT. When a two-word internal format time is specified to 
a function such as ITWAIT, it must have the high-order time as the first 
word and the low-order time as the second word. 

Form: CALL JJCVT (jsrc) 
where: 

jsrc is the INTEGER*4 variable whose contents are to be inter- 
changed 

Errors: 

None. 

Example: 

INTEGER*a TIME 



CALL GTIM(TIME) ! GET TIME OF DAY 

CALL JJCVT{TIME) ! TURN IT INTO INTEGER#4 FORMAT 

3.73 JMOV 

The JMOV function assigns the value of an INTEGER*4 variable to an- 
other INTEGER*4 variable and returns the sign of the value moved. 

Form: i = JMOV O'srcjdest) 

where: 

jsrc is the INTEGER*4 variable whose contents are to be moved 

jdest is the INTEGER*4 variable that is the target of the assign- 
ment 

Function Results: 

The value of the function is an INTEGER*2 value that represents the sign 
of the result as follows: 

i = -1 Normal return; the result is negative. 
= Normal return; the result is 0. 
= 1 Normal return; the result is positive. 
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Errors: 

None. 
Example: 

The JMOV function allows an INTEGER*4 quantity to be compared 
with by using it in a logical IF statement. For example: 

INTEGER*;^ INTl 

IF( JMOy( INTl (INTl ) .NE.O) GOTO 300 ! GO TO STMT 300 IF INTl NOT 

3.74 JMUL 

The JMUL function computes the product of two INTEGER*4 values. 

Form: i = JMUL (joprljopr2Jres) 

where: 

joprl is an INTEGER*4 variable that is the multiplicand 

jopr2 is an INTEGER*4 variable that is the multiplier 

jres is an INTEGER*4 variable that receives the product of the 
operation 

Function Results: 

i = -1 Normal return; the product is negative. 

- Normal return; the product is 0. 

- 1 Normal return; the product is positive. 

Errors: 

i = -2 An overflow occurred while computing the result. 
Example: 

INTEGER*^ Jl ,J2.JRES 



IF( JMULCJl ,J2 »JRES) + 1) 100 »10 .20 
C GOTO 100 IF OUERFLOW 
C GOTO 10 IF RESULT IS NEGATIVE 
C GOTO 20 IF RESULT IS POSITIUE OR ZERO 



3.75 JSUB 



The JSUB function computes the difference between two INTEGER*4 
values. 

Form: i = JSUB (joprl, jopr2,jres) 

where: 

joprl is an INTEGER*4 variable that is the minuend of the opera- 
tion 



System Subroutine Description and Examples 3-69 



jopr2 is an INTEGER*4 variable that is the subtrahend of the op- 
eration 

jres is an INTEGER*4 variable that is to receive the difference 
between jopri and jopr2 (that is, jres =joprl-jopr2) 

Function Results: 

i = -1 Normal return; the result is negative. 
= Normal return; the result is 0. 
= 1 Normal return; the result is positive. 

Errors: 

i = -2 An overflow occurred while computing the result. 

Example: 

INTEGER*a JOPl .J0P2iJ3 



CALL JSUB(J0P1 »J0P2.J3) 



3.76 JTME 



The JTIME subroutine converts the time specified to the internal two-word 
format time. 

Form: CALL JTIME (hrs,min,sec,tick,time) 
where: 

hrs is the integer number of hours 

min is the integer number of minutes 

sec is the integer number of seconds 

tick is the integer number of ticks (1/60 of a second for 60-cycle 
clocks; 1/50 of a second for 50-cycle clocks) 

time is the two- word area to receive the internal format time: 
timed) is the high-order time; time(2) is the low-order time 

Errors: 
Example: 

INTEGERS^ Jl 



CONCERT 3 HRS» 7 MIN, 23 SECONDS TO INTEGER *U UALUE 
CALL JTIME(3 ,7 ,23 ,0 .Jl) 
CALL JJC'TCJl) 
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3.77 LEN 



The LEN function returns the number of characters currently in the string 
contained in a specified array. This number is computed as the number of 
characters preceding the first null byte encountered. If the specified array 
contains a null string, a value of is returned. 

Form: i = LEN (a) 

where: 

a specifies the array containing the string, which must be termi- 
nated by a null byte 

Errors: 

None. 

Example: 

L0GICAL#1 STRNG(73) 



TYPE g9»(STRNG(I ) .1 = 1 .LEN(STRNG) ) 
99 FORMAT( '0' ,132A1) 



3.78 LOCK 



The LOCK subroutine keeps the USR in memory for a series of operations 
involving various RT-11 file management functions. 

If all the conditions that cause swapping are satisfied, a portion of the user 
program is written out to the disk file SWAP,SYS and the USR is loaded. 
Otherwise, the USR in memory is used, and no swapping occurs. The USR 
is not released until an UNLOCK (see Section 3.112) is given. (Note that in 
an FB system, calling the CSI can also perform an implicit UNLOCK.) To 
save time in swapping, a program that has many USR requests to make 
can LOCK the USR in memory, make all the requests, and then UNLOCK 
the USR. 

In an FB or XM environment, a LOCK inhibits another job from using the 
USR. Thus, the USR should be locked only for as long as necessary. 

NOTE 

If any job does a LOCK, it can cause the USR to be unavaila- 
ble for other jobs for a considerable period of time. The USR 
is not reentrant and only one job has use of the USR at a 
time, which should be considered for systems requiring con- 
current foreground and background jobs. This is particularly 
true when magtape and/or cassette are active. 

File operations by the USR require a sequential search of the 
tape for magtape and cassette. This could lock out the fore- 
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ground job for a long time while the background job does a 
tape operation. The programmer should keep this in mind 
when designing such systems. The FB and XM monitors sup- 
ply the ITLOCK routine, which permits the foreground job to 
check for the availability of the USR. 

Form: CALL LOCK 

After a LOCK has been executed, the UNLOCK routine must be executed 
to release the USR from memory. The LOCK/UNLOCK routines are com- 
plementary and must be matched. That is, if three LOCKs are issued, at 
least three UNLOCKS must be done, otherwise the USR is not released. 
More UNLOCKS than LOCKs can occur without error; the extra UN- 
LOCKS are ignored. 

Notes: 

1. It is vital that the LOCK call not come from within the area into which 
the USR will be swapped. If this should occur, the return from the USR 
request would not be to the user program, but to the USR itself, since 
the LOCK function causes part of the user program to be saved on disk 
and replaced in memory by the USR. Furthermore, subroutines, varia- 
bles, and arrays in the area where the USR is swapping should not be 
referenced while the USR is locked in memory. 

2. Once a LOCK has been performed, it is not advisable for the program to 
destroy the area the USR is in, even though no further use of the USR 
is required. This causes unpredictable results when an UNLOCK is 
done. 

3. LOCK cannot be called from a completion or interrupt routine. 

4. If a SET USR NOSWAP command has been issued, LOCK and UN- 
LOCK do not cause the USR to swap. However, in FB, LOCK still 
inhibits the other job from using the USR, and UNLOCK allows the 
other job access to the USR. 

5. The USR cannot accept argument lists, such as device file name specifi- 
cations, located in the area into which it has been locked. 

Errors: 

None. 
Example: 

INTEGER#2 DBLK(4) 

DATA DBLK /3RDK »3RDT t3RFIL »3RF^ / 



CALL LOCK !LOCK THE USR IN MEMORY 

ICHN=IGETC() ! GET A CHANNEL TO USE 

IF(LOOKUP(ICHN tDBLK) .LT.O) STOP ' 7L00KUP FAILED 
CALL UNLOCK ! RELEASE THE USR 
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3.79 LOOKUP 



The LOOKUP function associates a specified channel with a device and/or 
file for the purpose of performing I/O operations. The channel used is then 
busy until one of the following functions is executed. 

CLOSEC or ICLOSE 

ISAVES 

PURGE 

Form: i == LOOKUP (chan,dblk[,count,seqnum,]) 



i = LOOKUP (chanjobdes) 



where: 



chan 



dblk 



count 



seqnum 



jobdes 



is the integer specification for the RT-11 channel to be 
associated with the file. You must obtain this channel 
through an IGETC call, or you can use channel 16(deci- 
mal) or higher if you have done an ICDFN call 

is the four-word area specifying the Radix-50 file descrip- 
tor. Note that unpredictable results occur if the USR 
swaps over this four-word area 

is an optional argument used for the cassette handler; this 
argument defaults to 

is a file number. For cassette operations, if this argument 
is blank, a value of is assumed 

For magtape, it describes a file sequence number. The ac- 
tion taken depends on whether the file name is given or 
null. The sequence number can have the following values: 

-1 Suppress rewind and search for the specified file 
name from the current tape position. If a file name is 
given, a file-structured lookup is performed (do not 
rewind). If the file name is null, a non-file-structured 
lookup is done (tape is not moved). You must specify 
a -1 and no other negative number. 

Rewind to the beginning of the tape and do a non- 
file-structured lookup. 

n Where n is any positive number. Position the tape at 
file sequence number n and check that the file 
names match. If the file names do not match, an er- 

tured lookup is done on the file designated by seq- 
num. 

is an argument that allows communication between jobs 
in a system job environment. It is a pointer to a four- word 
job descriptor of the job to which messages will be sent or 
received. The syntax is 

jobdes -^ .RAD50 /MQ/ 

.ASCII /logical-job-name/ 
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where the logical -job -name is six characters long. If the 
logical-job -name is zero, the channel will be opened only 
for .READ/C/W requests, and such requests will accept 
messages from any jobs. 

liihejobdes argument is omitted, .LOOKUP operates as it 
did for Version 3B. 

NOTE 

The arguments of LOOKUP must be positioned so that the 
USR does not swap over them. 

The handler for the selected device must be in memory for a LOOKUP. If 
the first word of the file name in dblk is and the device is a file-structured 
device, absolute block of the device is designated as the beginning of the 
file. This technique, called a non-file-structured lookup, allows I/O to any 
physical block on the device. If a file name is specified for a device that is 
not file structured (such as LP:FILE.TYP), the name is ignored. 

NOTE 

Since a non-file-structured lookup allows I/O to any physical 
block on the device, the user must be aware that, in this 
mode, it is possible to overwrite the RT-11 device directory, 
thus destroying all file information on the device. 

Function Results: 

i = n Indicates a successful file-structured lookup on a random- 
access storage volume. 

i = Indicates a successful non-file-structured lookup on both 
random-access and non-file-structured volumes, or a suc- 
cessful file-structured lookup on magtape. 
Errors: 

> X i = -1 Channel specified is already open. 

= -2 File specified was not found on the device. 

= —3 Device in use. 

= -4 Tape drive is not available. 

= -5 Illegal argument error with a file-structured volume. 

= -6 Illegal argument error with a non-file-structured volume. 
Example: 

INTEGER^Z DBLK(a) 

DATA DBLK/3RDK0 .3RFTN .3R44 »3RDAT/ 



ICHAN=IGETC( ) 

IF( ICHAN.LT.O) STOP 'NO CHANNEL' 

IF( IFETCH(DBLK) .NE.O) STOP 'BAD FETCH' 

IF(LDOKUP( ICHAN ,DBLK) .LT.O) STOP 'BAD LOOKUP 
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CALL ICLOSE( ICHAN »I) 

I = ICLOSE( ) 

CALL IFREEC(ICHAN) 



or using LOOKUP with a system job 

LOGICAL*! JNAM(B) 
DIMENSION JBLK(4) 
EQUIVALENCE ( JNAM (1 ) . JBLK ( 2 ) ) 
DATA JNAM / 'Q ' , '\J ' , 'E ' , 'W , '£ ' >0/ 
DATA JBLK( 1 ) /3RM0 / 



PEN A MESSAGE CHANNEL TO 'QUEUE' 
CHN = GETC< ) 
F(LOOKUP(ICHNtJBLK) .LT.O) STOP 



'QUEUE IS NOT RUNNING' 



3.80 MRKT (SYSGEN Option in SJ) 

The MRKT function schedules an assembly language completion routine to 
be entered after a specified time interval has elapsed. Support for MRKT in 
SJ requires timer support. 



Form: i 
where: 
id 



MRKT (id,crtn,time) 



is an integer identification number to be passed to the routine 
being scheduled 

crtn is the name of the assembly language routine to be entered 
when the time interval elapses. This name must be specified 
in an EXTERNAL statement in the FORTRAN routine that 
issues the MRKT call 

time is the two-word, internal format time interval; when this in- 
terval elapses, the routine is entered. If considered as a two- 
element INTEGER*2 array: 

timed) is the high-order time. 
time(2) is the low-order time. 

Notes: 

1. MRKT requires a queue element, which should be considered when the 
IQSET function (Section 3.42) is executed. 

2. If the system is busy, the time interval that elapses before the comple- 
tion routine is run can be greater than that requested. 

For further information on scheduling completion routines, see the .MRKT 
programmed request (Section 2.49). 
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Errors: 



Normal return. 

1 No queue element was available; unable to schedule re- 
quest. 



Example: 



INTEGER*Z TINT(Z) 
EXTERNAL ARTIM 



CALL MRKT(4 tARTN »TINT) 



3.81 MTATCH (Special Feature) 

The MTATCH subroutine attaches a terminal for exclusive use by the re- 
questing job. This operation must be performed before any job can use a 
terminal with multiterminal programmed requests. 

Form: i = MTATCH (unit[,addr][,jobnum]) 

where: 

unit is the logical unit number ilun) of the terminal 

addr is the optional address of an asynchronous terminal status 

word. Omit this argument if the asynchronous terminal 
status word is not required by specifying a com.m-a. For 
example: 

I = MTATCH (unit„jobnum) 



jobnum 



Errors: 



i = 
= 3 
= 5 



= 6 



is the job number associated with the terminal if the ter- 
minal is not available 



Normal return. 
Nonexistent unit number. 

Unit attached by another job (job number returned in job- 
num) 

In XM monitor, the optional status word address is not in a 
valid user virtual address space 



Example: 



TEST SYSLIB MULTITERMINAL ROUTINES 

INTEGER*2 UNIT ,SBLDK(a) ,STftT(B) ,ASW .STRING (41 ) .PR0MT(8) 

LOGICAL*! TEND( 11 ) 

REAL»4 TESTMO) 

DATA PROMT/ 'EN' , 'TE' , 'R ' . ' ST ' . 'R I ' , 'NG ' , ' > ' ,"200/ 

DATA TEND/ '»'.'£', 'N'i'D',' ','T'.'E'.'S','T','#',0/ 

DATA TESTM/ 'STAT' . 'ATCH ' . 'GET' , 'SET' »'','','','', 'DTCH'/ 

USE MTSTAT TO GET & DISPLAY NO. OF UNITS 



TYPE lOG 

L=l 

IF(MTSTAT(STAT) .NE.O)GDTO 333 

TYPE 99 ,STAT(3) 



ANNOUNCE TEST 
L = FUNC CODE 
GET MTTY STATUS 
DISPLAY » UNITS 
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GET UNIT « TO TEST 

TYPE 100 ! TYPE PROMPT 

ACCEPT 101 fUNIT ! GET UNIT tt 

IF(UNIT.EQ.99) STOP 'END OF MULT I TERMI NAL TEST'! UNIT »9g STOPS TEST 

ATTACH UNIT TO THIS JOB THEN GET TCB STATUS WORDS 



TYPE 110 

ACCEPT 111 flASW 

IF( lASW.EO. 'Y' ) IER = MTATCH(UNIT .ASW .JOB) 

IFCIASW.NE. 'Y')IER = MTATCH(UNIT,0,JOB) 

L = 2 

IF( IER)GOTO 999 

L = 3 

IF(MTGET(UNIT .SBLOK( 1 ) ) .NE.0)G0T0 999 

TYPE 102 .UNIT .SBLOK 



! SEE IF ASW TEST 

! IS TO BE DONE 

! ATT W/ ASW IF YES 

! ATT W/0 ASW IF NO 

! REPORT ERROR IF ANY 

! GET TCB WORDS 

! DISPLAY CONTENTS 



GET NEW STATUS. PUT IT IN TCB. THEN DISPLAY IT 



CALL SETUP(SBLOK .UNIT) 

L=a 

IF(MTSET(UNIT , SBLOK ( 1 ) ) .NE.O)GOTO 999 
TYPE 102. UNIT. SBLOK 



! GET CHANGES IF ANY 

! GET NEW TCB STATUS 
! THEN DISPLAY IT. , . 



PERFORM TEST - FIRST ECHO INPUT THEN REPEAT IT USING MTIN & MTOUT 



20 TYPE 103 
TYPE 104 
TYPE 105 

30 CALL MTIN(UNIT .J) 
CALL MTOUT(UNIT.J) 
IF ( J. NE. 10) GOTO 30 
CALL MTRCTO(UNIT) 



! ANNOUNCE RULES OF 

! THE TEST. . . 

! GET LINE OF INPUT 

! REPEAT IST/ECHO 2ND 

! LF = END OF LINE 

! RESET CTRL/0 



ao 



50 
55 



NOW TEST W/ TTSPC$ BIT ON - ECHO INPUT WITH MTOUT (DON'T REPEAT) 
THEN TURN TTSPC$ BIT OFF. . . 



IF ( SBLOK (1 ) .AND, " 10000) GOTO 40 
SBLOK ( 1 )= SBLOK ( 1 ) .OR. "10000 
IF(MTSET(UNIT .SBLOK ( 1 ) ) . NE . ) GOTO 999 
GOTO 30 

SBLOK ( 1 )=SBLOK( 1 ) .AND. .NOT. "10000 
IF(MTSET(UNIT .SBLOK ( 1 ) ) .NE.O)GOTO 999 
IF( lASW.NE. 'Y ' )GOTO BO 



IF TTSPC$ ON BRANCH 

SET TTSPC$ BIT 

UPDATE TCB 

GO DO 2ND TEST 

TURN OFF TTSPC$ BIT 

UPDATE TCB 

SKIP ASW TEST? 



ASYNCHRONOUS STATUS WORD TEST - "POLL" TERMINAL UNTIL INPUT 
AUAILABLE - ECHO INPUT THEN REPEAT IT ON NEXT LINE 



TYPE 109 

IF( .NOT. ASW. AND. "40000) GOTO 50 

CALL MTIN(UNIT .J) 

CALL MTOUT(UNIT .J) 

IF( J.NE. 10)G0T0 55 

CALL MTRCTO(UNIT) 



ANNOUNCE TEST 
WAIT FDR INPUT 
GET CHAR 
OUTPUT CHAR 
END ON LINE FEED 
RESET CTRL/0 



C 
SO 



TEST MTPRNT BY OUTPUTTING 2 STRINGS . 1 FROM USER &: 1 INTERNAL 



CALL GTLIN(STRING. PROMT) 
CALL MTPRNT(UNIT .STRING) 
CALL MTPRNT(UNIT .TEND) 



GET STRING VIA GTLIN 
OUTPUT TO TERMINAL 
ANNOUNCE END OF TEST 



DETACH UNIT FROM JOB AND START OMER 



L = 9 

TYPE 108 .UNIT 

IF(MTDTCH(UNIT) .EO.O)GOTO 5 



! DETATCH UNIT 

! FROM JOB THEN LOOP 
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c 

999 



99 

100 

101 

102 

103 

loa 

105 
lOG 
108 
109 
110 
111 
909 



ERROR REPORTING 

TYPE 909 ,TESTM(L) tIER 
GOTO 5 



! ANNOUNCE ERROR 
! THEN START OMER 



1 
101 
102 
103 
104 
105 



FORMAT( 
FORMAT( 
FORMAT( 
FORMAT( 
FORMAT ( 



FORMAT( 'OTHERE ARE'. 13.' UNITS ON THIS SYSTEM') 

FORMAT( '*UNIT « TO 6E TESTED?') 

FDRMAT( 12) 

FORMAT( 'OUNIT' .13 . ' STATUS ='.408) 

FORMAT('OGO TO TERMINAL BEING TESTED ... ENTER 2 LINES + m') 

■ 1ST LINE: INPUT WILL BE ECHOED THEN REPEATED') 
2ND LINE: TEST TTSPC* ON - INPUT ECHOED UIA MTOUT'/) 

1 SYSLIB MULTITERMINAL ROUTINE TEST PROGRAM') 

■ ABOUT TO DETACH UNIT « '.12) 

■ TEST ASH - INPUT WILL BE ECHOED. THEN REPEATED'/) 
FDRMATC '$TEST ASYNCH STATUS WORD FUNCTION?') 

F0RMAT(A1 ) 

FORMAT( 'OMT' .A4 . ' ERROR CODE ='.I3) 

END 

SUBROUTINE TO GET NEW STATUS WORD MALUES 



SUBROUTINE SETUP ( SBLOK .UN I T ) 

INTEGER SBL0K(4) .UNIT 

TYPE 100 

ACCEPT 101 iJ 

IF( J)SBLOK( 1 )=J 

TYPE 102 

ACCEPT 101 .J 

TYPE 103 

ACCEPT 101 ,1 

IFC I .OR. J)SBL0K(3)=I»25S+J 

TYPE 104 

ACCEPT 105.1 

IF( I )SBL0K(4)=SBL0K(4)/25B*25B+I 

RETURN 

FORMAT( '$CDNFIG BIT MASK:') 

FORMAT(OS) 

FORMAT( '$CHAR REQUIRING FILLER:') 

FORMAT('*» OF FILL CHARS:') 

FORMAT( '$CARRIAGE WIDTH:') 

FORMAT( 13) 

END 



PROMPT FOR NEW CONFIG WORD 

ACCEPT INPUT 

UPDATE IF ANY INPUT 

ASK FDR FILL CHAR 

ACCEPT IT 

ASK FOR « OF FILL CHARS 

ACCEPT IT TOO 

PUT IN PROPER BYTES 

ASK FOR CARRIAGE WIDTH 

ACCEPT IT 

SET BUT DON'T MESS WITH 

STATE WORD . , . RETURN 



3.82 MTDTCH (Special Feature) 

The MTDTCH subroutine is the complement of the MTATCH subroutine. 
Its function is to detach a terminal from a particular job and make it avail- 
able for other jobs. 

Form: i = MTDTCH(unit) 

where: 

unit is the logical unit number (/wn) of the terminal to be detached 

Errors: 

i = Normal return. 
= 2 Invalid unit number; terminal is not attached. 
= 3 Nonexistent unit number. 
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Example: 

Refer to the example under MTATCH. 

3.83 MTGET (Special Feature) 

The MTGET subroutine furnishes the user with information about a spe- 
cific terminal in a multiterminal system. You do not need to do an 
MTATCH before using MTGET. 

Form: i = MTGET (unit,addr[,jobnum]) 

where: 

unit is the unit number of the line and terminal whose status is 

desired 

addr is the four-word area to receive the status information. The 

area is a four-element INTEGER*2 array (see the .MTSET 
programmed request, Section 2.58, for area format) 

jobnum is the job number associated with the terminal if the termi- 
nal is not available 

Status information including bit definitions for the terminal configuration 
words and the terminal state byte are described in detail under the 
.MTGET programmed request. 

Errors: 

i = Normal return. 
= 2 Unit not attached. 
= 3 Nonexistent unit number. 
= 4 Unit attached by another job (job number returned in jo6- 

num). 
= 6 In XM monitor, the address of the terminal buffer is outside 

the valid program limits. 

Example: 

Refer to the example under MTATCH. 

3.34 MTIN (Special Feature) 

The MTIN subroutine transfers characters from a specified terminal to the 
user program. This subroutine is a multiterminal form of ITTINR. If no 
characters are available, an error flag is set to indicate an error upon re- 
turn from the subroutine. If no character count argument is specified, one 
character is transferred. 

Form: i = MTIN (unit,char[,chrcnt ][,ocnt]) 

where: 

unit is the unit number of the terminal 

char is the variable to contain the characters read in from the 
terminal indicated by the unit number 
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chrcnt is an optional argument that indicates the number of char- 
acters to be read 

ocnt is an optional argument that indicates the number of char- 

acters actually transferred 

When a request for a multiple-character transfer is requested, if the op- 
tional fourth argument {ocnt) is specified and bit 6 of the M.TSTS word is 
set, the variable specified as the argument will have a value equal to the 
actual number of characters transferred upon return from the subroutine. 

Errors: 

i = Normal return. 

= 1 No input available. 

= 2 Unit not attached. 

= 3 Nonexistent unit number. 

Example: 

Refer to the example under MTATCH. 



3.85 MTOUT (Special Feature) 



The MTOUT subroutine transfers characters to a specified terminal. This 
subroutine is a multiterminal form of ITTOUR. If no room is available in 
the output ring buffer, an error flag is set to indicate an error upon return 
from the subroutine. If no character count argument is specified, one char- 
acter is transferred. 

Form: i = MTOUT (unit,char[,chrcnt][,ocnt]) 

where: 

unit is the unit number of the terminal 

char is the variable or array containing the characters to be out- 
put, right-justified in the integer (can be LOGICAL*! if de- 
sired) 

chrcnt is an optional argument that indicates the number of char- 
acters to be output 

ocnt is an optional argument that indicates the number of char- 

acters actually transferred 

When a request for a multiple-character transfer is requested, if the op- 
tional fourth argument {ocnt) is specified and bit 6 of the M.TSTS word is 
set, the variable specified as the argument will have a value equal to the 






r^ntTf* r 



Errors: 



Normal return. 

1 No room in output ring buffer. 

2 Unit not attached. 

3 Nonexistent unit number. 

5 In the XM monitor, the address of the user buffer is outside 
the valid program limits. 
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Example: 

Refer to the example under MTATCH. 

3.86 MTPRUT (Special Feature) 

The MTPRNT subroutine allows output to be printed at any terminal in a 
multiterminal environment. This subroutine has the same effect as the 
PRINT subroutine (Section 3.91). 

Form: i = MTPRNT (unit,string) 

where: 

unit is the unnit number associated with the terminal 

string is the character string to be printed. Note that all quoted 
literals used in FORTRAN subroutine calls are in ASCIZ 
format, which ends in zero for a CR/LF or a 200 if no action 
is to be taken 

Errors: 

i = Normal return. 
= 2 Unit not attached. 
= 3 Nonexistent unit number. 

= 5 In the XM monitor, the address of the character string is 
outside the valid program limits. 

3.87 MTRCTO (Special Feature) 

The MTRCTO subroutine resets the CTRL/0 command typed at the speci- 
fied terminal in a multiterminal environment. This subroutine has the 
same effect as the .MTRCTO programmed request (Section 2.57). 

Form: i = MTRCTO(unit) 

where: 

unit is the unit number associated with the terminal 

Errors: 

i = Normal return. 
= 2 Unit not attached. 
= 3 Nonexistent unit number. 

Example: 

Refer to the example under MTATCH. 



3.88 MTSET (Special Feature) 



The MTSET subroutine sets terminal and line characteristics. The set con- 
ditions remain in effect until the system is booted or the terminal and line 
characteristics are reset. See the .MTSET programmed request (Section 
2.58) for more details. 
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Form: i = 
where: 

unit 



addr 



MTSET (unit,addr) 



is the unit number of the line and terminal whose character- 
istics are to be changed 

is a four-word area to pass the status information. The area is 
a four-element INTEGER*2 array 



Errors: 



Normal return. 

2 Unit not attached. 

3 Nonexistent unit number. 

6 In the XM monitor, the address of the status block is outside 
the valid program limits. 



Example: 



Refer to the example under MTATCH. 

3.89 MTSTAT (Special Feature) 

The MTSTAT subroutine returns multiterminal system status in an eight- 
word status block. 

Form: i = MTSTAT (addr) 

where: 

addr is the address of an eight-word array where multiterminal 
status information is returned. The status block contains the 
following information: 

Contents 

addr(l) Offset from the base of the resident monitor to 

the first Terminal Control Block (TCB). 

addr(2) Offset from the base of the resident monitor to 

the terminal control block of the console termi- 
nal for the program. 

addr(3) The value (0-16 decimal) of the highest logical 

unit number (LUN) built into the system. 

addr(4) The size of the terminal control block in bytes. 

addr(5)-(8) Reserved. 



Errors: 



i = Normal return. 

= 5 In the XM monitor, the address of the status block is not in 
valid user address space. 

Example: 

Refer to the example under MTATCH. 
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3.90 MWAIT (FB and XM Only) 

The MWAIT subroutine suspends main program execution of the current 
job until all messages sent to or from the other job have been transmitted or 
received. It provides a means for ensuring that a required message has 
been processed. MWAIT is used primarily in conjunction with the IRCVD 
and ISDAT calls, where no action is taken when a message transmission is 
completed. This subroutine requires a queue element, which should be con- 
sidered when the IQSET function (Section 3.42) is executed. 

Form: CALL MWAIT 

Errors: 

None. 
Example: 

Refer to the example under ISDAT, Section 3.51. 



3.91 PRINT 



The PRINT subroutine prints output from a specified string at the console 
terminal. This routine can be used to print messages from completion 
routines without using the FORTRAN formatted I/O system. Control re- 
turns to the user program after all characters have been placed in the 
output buffer. 

The string to be printed can be terminated with either a null (0) byte or a 
200(octal) byte. If the null (ASCIZ) format is used, the output is automati- 
cally followed by a carriage return/line feed pair (octal 15 and 12). If a 200 
byte terminates the string, no carriage return/line feed pair is generated. 

In the FB monitor, a change in the job that is controlling terminal output is 
indicated by a B> or F>. Any text following the message has been printed 
by the job indicated (foreground or background) until another B> or F> is 
printed. When PRINT is used by the foreground job, the message appears 
immediately, regardless of the state of the background job. Thus, for urgent 
messages, PRINT should be used rather than ITTOUR. 

Form: CALL PRINT (string) 

where: 

string is the string to be printed. Note that ail quoted literals used 
in FORTRAN subroutine calls are in ASCIZ format, as are 
all strings produced by the SYSLIB string-handling package 
(The CONCAT routine can be used to append an octal 200 to 
an ASCIZ string; see example.) 

Errors: 

None. 
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Example: 

CALL PRINT ('THE COFFEE IS READY') 

r 

BYTE QUEST I ON (BO) 

! APPEND BYTE ZOO 

CALL CONCAT('WHAT IS YOUR NAME? . " ZOO lOUESTI ON ) 

CALL PRINT(OUESTION) lOUESTION PRINTS WITHOUT CR iLF 



3.92 PURGE 



The PURGE subroutine deactivates a channel without performing an 
ISAVES, CLOSEC, or ICLOSE. Any tentative file currently associated 
with the channel is not made permanent. This subroutine prevents entered 
(TENTER or .ENTER) files firom becoming permanent directory entries. 

Form: CALL PURGE (chan) 

where: 

chan is the integer specification for the RT-11 channel to be deac- 
tivated 

Errors: 

None. 
Example: 

Refer to the example under TENTER, Section 3.25. 



3.93 PUTSTR 



The PUTSTR subroutine writes a variable-length character string to a 
specified FORTRAN logical unit. PUTSTR can be used in main program 
routines or in completion routines but not in both in the same program at 
the same time. If PUTSTR is used in a completion routine, it must not be 
the first I/O operation on the specified logical unit. 

Form: CALL PUTSTR (lun,in,char,err) 

where: 

lun is the integer specification of the FORTRAN logical unit 
number to which the string is to be written 

in is the array containing the string to be written 

char is an ASCII character that is appended to the beginning of the 
string before it is output. If 0, no extra character is output. 
This character is used primarily for carriage control purposes 

err is a LOGICAL*! variable that is .TRUE, for an error condi- 
tion and .FALSE, for a no-error condition 
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Errors: 

err = -1 End-of-flle for write operation. 

-2 Hardware error for write operation. 

Example: 

LOGICAL*! STRNG(B1 ) ,ERR 



lOUTPUT STRING WITH DOUBLE SPACING 
CALL PUTSTR(7 .STRNG » '0' ,ERR) 



3.94 R50ASC 



The R50ASC subroutine converts a specified number of Radix-50 charac- 
ters to ASCII. 

Form: CALL R50ASC (icnt,input,output) 



' where: 



icnt is the integer number of ASCII characters to be produced 

input is the area from which words of Radix-50 values to be con- 
verted are taken. Note that {icnt + 2)IZ words are read for 
conversion 

output is the area into which the ASCII characters are stored 

Errors: 

If an input word contains illegal Radix-50 codes — that is, if the 
input word is greater (unsigned) than 174777(octal) — the routine 
outputs question marks for the value. 

Example: 

REAL*B NAME 
LOGICAL*! OUTP(IZ) 



CALL R50ASC(!2tNAME tOUTP) 

3.95 RAD50 

The RAD50 function provides a method of encoding RT-11 file descriptors 
in Radix-50 notation. The RAD50 function converts six ASCII characters 
from the specified area, returning a REAL*4 result that is the two-word 
Radix-50 value. 

Form: a - RAD50 (input) 

where: 

input is the area from which the ASCII input characters are taken 
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The RAD50 call: 

A = RAD50 (LINE) 

is exactly equivalent to the IRAD50 call: 

CALL IRAD50 (G.LINEiA) 

Function Results: 

The two-word Radix-50 value is returned as the function result. 



3.96 RCHAIN 



The RCHAIN subroutine allows a program to determine whether it has 
been chained to and to access variables passed across a chain. If RCHAIN is 
used, it must be used in the first executable FORTRAN statement in a 
program. 

Form: CALL RCHAIN (flag,var,wcnt) 

where: 

flag is an integer variable that RCHAIN will set to -1 (true) if the 
program has been chained to; otherwise, it is (false) 

var is the first variable in a sequence of variables with increasing 
memory addresses to receive the information passed across 
the chain (see Section 3.2) 

went is the number of words to be moved from the chain parameter 
area to the area specified by var. RCHAIN moves went words 
into the area beginning at var 

Errors: 

None. 

Example: 

INTEGER#2 PARMS(50) 

CALL RCHAIN( IFLAG tPARMS »50) 

IF(IFLAG) GOTO 10 ! GOTO 10 IF CHAINED TO 



3.97 RCTRLO 



The RCTRLO subroutine resets the effect of any console terminal CTRL/0 
command that was typed. After an RCTRLO call, any output directed to the 
console terminal prints until another CTRL/0 is typed. 

Form: CALL RCTRLO 

Errors: 

None. 
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Example: 



CALL RCTRLO 

CALL PRINT ('PRINT UNTIL ANOTHER CTRL/D TYPED') 



3.98 REPEAT 



The REPEAT subroutine concatenates a specified string with itself to pro- 
duce the indicated number of copies. REPEAT places the resulting string in 
a specified array. 

Form: CALL REPEAT (in,out,i[,len[,err]]) 

where: 

in is the array containing the string to be repeated; it must be 
terminated with a null byte 

out is the array into which the resultant string is placed. This 
array must be at least one element longer than the value of 
len, if len is specified. It also must be terminated with a null 
byte if len is specified 

i is the integer number of times to repeat the string 

len is the integer number representing the maximum length of the 
output string 

err is the logical error flag set if the output string is truncated to 
the length specified by len 

Input and output strings can specify the same array only if the repeat count 
(i) is 1 or 0. When the repeat count is 1, this routine is the equivalent of 
SCOPY; when the repeat count is 0, out is replaced by a null string. The old 
contents of out are lost when this routine is called. 

Errors: 

Error conditions are indicated by err, if specified. If err is given and 
the output string would have been longer than len characters, then 
err is set to .TRUE.; otherwise, err is unchanged. 

Example: 

LOGICAL*! SIN(21) .SOUT(lOl) 



CALL REPEAT(SIN tSOUT .5) 

3.99 RESUME (FB and XM Only) 

The RESUME subroutine allows a job to resume execution of the main 
program. A RESUME call is normally issued from an asynchronous FOR- 
TRAN routine entered on I/O completion or because of a schedule request 
(see the SUSPND subroutine. Section 3.107, for more information). 
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Form: CALL RESUME 
Errors: 

None. 
Example: 

Refer to the example under SUSPND. 

3.100 SCCA 

The SCCA subroutine provides a CTRL/C intercept to: 

1. Inhibit a CTRL/C abort 

2. Indicate that a CTRL/C command is active 

3. Distinguish between single and double CTRL/C commands 

Form: CALL SCCA [(iflag)] 
where: 

iflag is an integer terminal status word that must be tested and 
cleared to determine if two CTRL/Cs were typed at the con- 
sole terminal; the iflag must be an INTEGER*2 variable (not 
LOGICAL*!) 

When a CTRL/C is typed, the SCCA subroutine places it in the input ring 
buffer. While residing in the buffer, the character can be read by the pro- 
gram. The program must test and clear the iflag to determine if two 
CTRL/C commands were typed consecutively. The iflag is set to non-zero 
when two CTRL/Cs are typed together. It is the responsibility of the pro- 
gram to abort itself, if appropriate, on an input of CTRL/C from the termi- 
nal. The SCCA subroutine with no argument disables the CTRL/C inter- 
cept. A CTRL/C from indirect command files is not intercepted by SCCA. 

Errors: 

None. 

Example: 

PROGRAM SCCA 
C SCCA. FDR SYSLIB TEST FOR SCCA 
C 

CALL PRINT ('PROGRAM HAS STARTED) TYPE') 

IFLAG=0 

CALL SCCA (IFLAG) 

(A T - TTTTMD/\ \ TCT i\ ru f\a i\n c ri 

J..-' ^ ~ AiiAiii\\/ :ui_i nt.'iir-ii\ni.jii_i\ 

IF (I .NE. 3) GOTO 10 
C A CTRL/C WAS TYPED 

CALL PRINT ('A CTRL/C WAS TYPED') 

IF (IFLAG ,E0. 0) GOTO 10 

CALL PRINT ('A DOUBLE CTRL/C WAS TYPED') 

TYPE lOtlFLAG 

19 FORMAT ( ' IFLAG = ' .06 ./) 

CALL SCCA [DISABLE CTRL/C INTERCEPT 

CALL PRINT ('TYPE A CTRL/C TO EXIT') 

20 GOTO 20 ILOOP UNTIL CTRL/C TYPED 
END 
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3.101 SCOMP/ISCOMP 

The SCOMP routine compares two character strings and returns the inte- 
ger result of the comparison. 

Form 1: CALL SCOMP (a,b,i) 

or 

i = ISCOMP(a,b) 

Form 2: CALL ISCOMP (a,b,i) 

or 

i = SCOMP (a,b) 

where: 

a is the array containing the first string; it must be terminated 
with a null byte 

b is the array containing the second string; it must be terminated 
with a null byte 

i is the integer variable that receives the result of the comparison 

The strings are compared from left to right, one character at a time, using 
the collating sequence specified by the ASCII codes for each character. If 
the two strings are not equal, the absolute value of variable i (or the result 
of the function ISCOMP) is the character position of the first inequality 
found. Strings are terminated by a null (0) character. 

If the strings are not the same length, the shorter one is treated as if it 
were padded on the right with blanks to the length of the other string. A 
null string argument is equivalent to a string containing only blanks. 

Function Results: 

i <0 If a is less than b. 
= If a is equal to b. 
>0 If a is greater than 6. 

Example: 

LOGICAL*! liMSTR(Bl) 



CALL GETSTR(5»INSTR»80) 

CALL SCOMP ( 'YES' tlNSTR »IMAL) 

IF( IMAL.NE.O) GOTO 10 ! IF INPUT STRING IS NOT YES GOTO 10 

3.102 SCOPY 

The SCOPY routine copies a character string from one array to another. 
Copying stops either when a null (0) character is encountered or when a 
specified number of characters have been moved. 

Form: CALL SCOPY (in,out[,len[,err]]) 

where: 

in is the array containing the string to be copied; it must be ter- 
minated with a null byte if len is not specified, or if the string 
is shorter than len 
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out is the array to receive the copied string. This array must be at 
least one element longer than the value of len, if len is speci- 
fied. It also must be terminated with a null byte if len is speci- 
fied 

len is the integer number representing the maximum length of the 
output string. The effect of len is to truncate the output string 
to a given length 

err is a logical variable that receives the error indication if the 
output string was truncated to the length specified by len 

The input {in) and output (out) arguments can specify the same array. The 
string previously contained in the output array is lost when this subroutine 
is called. 



Errors: 



Error conditions are indicated by err, if specified. If err is given and 
the output string was truncated to the length specified by len, then 
err is set to .TRUE.; otherwise, err is unchanged. 



Example: 



SCOPY is useful for initializing strings to a constant value, for exam- 
ple: 



L0GICAL«1 STRING(80) 

CALL SCOPY('THIS IS THE INITIAL UALUE ' ,STR ING ) 



3.103 SECNDS 



The SECNDS function returns the current system time, in seconds past 
midnight, minus the value of a specified argument. Thus, SECNDS can be 
used to calculate elapsed time. The value returned is single-precision float- 
ing point (REAL*4). 

Form: a = SECNDS (atime) 

where: 

atime is a REAL*4 variable, constant, or expression whose value is 
subtracted from the current time of day to form the result 

Notes: 

This function does floating-point arithmetic. Elapsed time can also be cal- 
culated by using the GTIM call and the INTEGER*4 support functions. 

Function Result: 

The function result (a) is the REAL*4 value returned. 

Errors: 

None. 
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Example: 

X C START OF TIMED SEQUENCE 

I T1=SECNDS(0. ) 

C 

C CODE TO BE TIMED GOES HERE 

C 

DELTA = SECNDS(T1 ) ! DELTA IS ELAPSED TIME 

3.104 SETCMD 

The SETCMD routine allows a user program to pass a command line to the 
keyboard monitor to be executed after the program exits. This routine can 
be used in a program running under the SJ monitor, or in a program run- 
ning in the background under the FB or XM monitor. The command lines 
are passed to the chain information area (500-777 octal) and stored begin- 
ning at location 512(octal). No check is made to determine if the string 
extends into the stack space. For this reason, the command line should be 
short and the subroutine call should be made in the main program unit 
^ near the end of the program just before completion. When several com- 

I mands are involved, an indirect command file that contains several com- 

mand lines should be used. 

The monitor commands REENTER, START, and CLOSE are not allowed if 
the SETCMD feature is used. 

Form: CALL SETCMD (string) 

where: 

\ string is a keyboard monitor command line in ASCIZ format with 

' no embedded carriage returns or line feeds 

Errors: 

None. 

Example: 

LOGICAL*! INPUT(13<a) »PROMPT(B) 

DATA PROMPT/ ' P ' . ' R ' » '0 ' » 'M ' » ' P ' » ' T ' . ' > ' t"200/ 

) CALL GTLIN (INPUT. PROMPT) 

' CALL SETCMD (INPUT) 

END 

NOTE 

Set USR NOSWAP, or specify /NOSWAP with the COM- 
PILE, FORTRAN, or EXECUTE command to control the 
swapping state of the USR. A LOCK would inhibit another 
job from using the USR. 

A STOP or CALL EXIT must also be issued after the SETCMD to cause an 
exit. 



3.105 STRPAD 



The STRPAD routine pads a character string with rightmost blanks until 
that string is a specified length. This padding is done in place; the result 



System Subroutine Description and Examples 3-91 



string is contained in its original array. If the present length of the string is 
greater than or equal to the specified length, no padding occurs. 

Form: CALL STRPAD (a,len[,err]) 

where: 

a is the array containing the string to be padded. This array 
must be one element longer than the value of len if len is speci- 
fied. It will be terminated by a null byte 

len is the integer length of the desired result string 

err is the logical error flag that is set to .TRUE, if the string speci- 
fied by a exceeds the value of len in length 



Errors: 



Error conditions are indicated by err, if specified. If err is given and 
the string indicated is longer than len characters, err is set to .TRUE.; 
otherwise, the value of err is unchanged. 



Example: 



This routine is especially useful for preparing strings to be output in 
A-type FORMAT fields. For example: 



LOGICAL*! STR(81) 



CALL STRPAD(STR»80) ! ASSURE 80 UALID CHARACTERS 
PRINT 100 »(STR(I ) .1 = 1 .80) ! PRINT STRING OF 80 CHARACTERS 
100 FORMAT (80A1) 



3.106 SUBSTR 



The SUBSTR routine copies a substring from a specified position in a char- 
acter string. If desired, the substring can then be placed in the same array 
as the string from which it was taken. 

Form: CALL SUBSTR (in,out,i[,len]) 

where: 

in is the array from which the substring is taken; it is terminated 
by a null byte 

out is the array to contain the substring result. This array must be 
one element longer than len, if len is specified. It also is termi- 
nated by a null byte if len is specified 

i is the integer character position in the input string of the first 

character of the desired substring 

len is the integer number of characters representing the maximum 
length of the substring 
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If a maximum length (len) is not given, the substring contains all charac- 
ters to the right of character position i in array in and is not terminated by 
a null byte. If len is given, the string is copied and terminated with a null 
byte. If len is equal to zero, out is replaced by the null string. The old 
contents of array out are lost when this routine is called. 

Errors: 

None. 

3.107 SUSPND (FB and KM Only) 

The SUSPND subroutine suspends main program execution of the current 
job and allows only completion routines (for I/O and scheduling requests) to 
run. 

Form: CALL SUSPND 

Notes: 

1. The monitor maintains a suspension counter for each job. This count is 
decremented by SUSPND and incremented by RESUME (see Section 
3.99). A job will actually be suspended only if this counter is negative. 
Thus, if a RESUME is issued before a SUSPND, the latter routine will 
return immediately. 

2. A program must issue an equal number of SUSPND and RESUME 
calls. 

3. A SUSPND subroutine call from a completion routine decrements the 
suspension counter but does not suspend the main program. If a comple- 
tion routine does a SUSPND, the main program continues until it also 
issues a SUSPND, at which time it is suspended. Two RESUME calls 
are then required to proceed. 

4. Because SUSPND and RESUME are used to simulate an ITWAIT (see 
Section 3.61) in the monitor, a RESUME issued from a completion rou- 
tine and not matched by a previously executed SUSPND can cause the 
main program execution to continue past a timed wait before the entire 
time interval has elapsed. 

For further information on suspending main program execution of the cur- 
rent job, see the .SPND programmed request (Section 2.89). 

Errors: 

None. 

Example: 

INTEGER lAREA(^) 

COMMON /RDBLK/ IBUF(25B) 

EXTERNAL RDFIN 
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IF(IREADF(25G»IBUFtIBLK .ICHANdAREA.RDFIN) .NE.O) GOTO 1000 
C GOTO 1000. FOR ANY TYPE OF ERROR 
C 
C DO OVERLAPPED PROCESSING 



CALL SUSPND ISYNCHRONIZE WITH COMPLETION ROUTINE 



END 

SUBROUTINE RDF IN ( I ARGl » I ARG2 ) 

COMMON /RDBLK/ IBUF(Z5G) 



CALL RESUME ICONTINUE MAIN PROGRAM 



END 



3.108 TIMASC 



The TIMASC subroutine converts a two-word internal format time into an 
ASCII string of the form: 

hh:mm:ss 
where: 

hh is the two-digit hours indication ) 

mm is the two-digit minutes indication 

ss is the two-digit seconds indication 
Form: CALL TIMASC (itime.strng) 
where: 

itime is the two-word internal format time to be converted. > 

itime(l) is the high-order time, itime(2) is the low-order time 

strng is the eight-element array to contain the ASCII time 
Errors: 

None. 

Example: 

The following example determines the amount of time from the time 
the program is run until 5 p.m. and prints it. 

INTEGER*^ Jl »J2 tJ3 
L0GICAL*1 STRNG(8) 
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CALL JTIME( 17 .0 .0 »0 •Jl) 
CALL GTIM(J2) 
CALL JJCMT( Jl ) 
CALL JJCVKJS) 
CALL JSUB( Jl »J2 »J3) 
CALL JJCVT(J3) 
CALL TIMASC( J3 tSTRNG) 
TYPE 99 tCSTRNGd ) .1 = 1 ,B) 
99 FORMAK' IT 19 'iBAl.' TILL 5 P.M.') 



3.109 TIME 



The TIME subroutine returns the current system time of day as an eight- 
character ASCII string of the form: 

hh:mm:ss 
where: 

hh is the two-digit hours indication 

mm is the two-digit minutes indication 

ss is the two-digit seconds indication 
Form: CALL TIME (strng) 
where: 

strng is the eight-element array to receive the ASCII time 
Notes: 

A 24-hour clock is used (for example, 1:00 p.m. is represented as 13:00:00). 
Errors: 

None. 
Example: 

LQGICAL-sl STRNGCB) 



CALL TIME(STRNG) 
TYPE g9i(9TRNG( I) .1 = 1 .8) 
99 FORMAT (' IT IS NOW '.BAD 



3.110 TRANSL 



The TRANSL routine performs character translation on a specified string 
and requires approximately 64(decimal) words on the R6 stack for its exe- 
cution. This space should be considered when allocating stack space. 

Form: CALL TRANSL (in,out,r[,p]) 
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where: 

in is the array containing the input string; it is terminated by a 
null byte 

out is the array to receive the translated string; it is not termi- 
nated by a null byte 

r is the array containing the replacement string; it is terminated 

by a null byte 

p is the array containing the characters in in to be translated; it 

is terminated by a null byte 

The string specified by array out is replaced by the string specified by array 
in, modified by the character translation process specified by arrays r and 
p. If any character position in in contains a character that appears in the 
string specified by p, it is replaced in out by the corresponding character 
from string r. If the array p is omitted, it is assumed to be the 127 seven-bit 
ASCII characters arranged in ascending order, beginning with the charac- 
ter whose ASCII code is 001. If strings r and p are given and differ in 
length, the longer string is truncated to the length of the shorter. If a 
character appears more than once in string p, only the last occurrence is 
significant. A character can appear any number of times in string r. 

Errors: 

None. 

Examples: 

The following example causes the string in array A to be copied to 
array B. All periods within A become minus signs, and all question 
marks become exclamation points. 

CALL TRANSL(A »B » '- ! ' t ' .?' ) 

The following is an example of TRANSL being used to format charac- 
ter data. 

L0GICAL#1 STRING(27) .RESULT(27) .PATRN(27) 
C SET UP THE STRING TO BE REFORMATTED 
C 

CALL SCOPY( 'THE HORN BLOWS AT MIDNIGHT ' .STRING ) 
C SET UP NUMBER-CHARACTER DATA RELATIONSHIP 
C 

C 00000000011111111112222222 
C 12345S789012345B789012345B 
C THE HORN BLOWS AT MIDNIGHT 

C NOW SET UP PATRN TO CONTAIN THE FOLLOWING PATTERN: 

C lB.17fl8il9.20.21 . 22. 23. 24. 25. 2B. 15.1 .2. 3. 4. 5.6. 7. 8. 9. 10. 11 .12.13.14.0 
C 

DO 10 I=1B.2B 
10 PATRN( I-15)=I 

PATRN( 12)=15 

DO 20 1=1.14 
20 PATRN( I+12)=I 

PATRN(27)=0 
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c 

C THE FOLLOWING CALL TO TRANSL REARRANGES THE CHARACTERS OF 

C THE INPUT STRING TO THE ORDER SPECIFIED BY PATRN; 

C 

CALL TRANSL(PATRN .RESULT (STRING) 
C 

C RESULT NOW CONTAINS THE STRING 'AT MIDNIGHT THE HORN BLOWS' 

C IN GENERAL, THIS METHOD CAN BE USED TO FORMAT INPUT STRINGS 

C OF UP TO 127 CHARACTERS. THE RESULTANT STRING WILL BE 

C AS LONG AS THE PATTERN STRING (AS IN THE ABO^E EXAMPLE). 



3.111 TRIM 



The TRIM routine shortens a specified character string by removing all 
trailing blanks. A trailing blank is a blank that has no non-blanks to its 
right. If the specified string contains all blank characters, it is replaced by 
the null string. If the specified string has no trailing blanks, it is un- 
changed. 

Form: CALL TRIM (a) 

where: 

a is the array containing the string to be trimmed; it is terminated 
by a null byte on input and output 

Errors: 

None. 

Example: 

LOGICAL*! STRING(81) 
ACCEPT 100 ,(STRING(I) ,1 = 1 ,80) 
100 FORMAT(BOAl) 

CALL SCOPY(STRING (STRING, 80) !MAKE ASCIZ 

CALL TRIM(STRING) ITRIM TRAILING BLANKS 



3.112 UNLOCK 



The UNLOCK subroutine releases the User Service Routine (USR) from 
memory if it was placed there by the LOCK routine. If the LOCK required 
a swap, the UNLOCK loads the user program back into memory. If the 
USR does not require swapping, the UNLOCK involves no I/O. The USR is 
always resident in XM. 

Form: CALL UNLOCK 

Notes: 

1. It is important that at least as many UNLOCK calls are given as 
LOCK calls. If more LOCK calls were done, the USR remains locked in 
memory. Extra UNLOCK calls are ignored. 

2. When running two jobs in the FB system, use the LOCK/UNLOCK 
pairs only when absolutely necessary. If one job locks the USR, the 
other job cannot use the USR until it is unlocked. 
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3. In an FB system, calling the CSI (ICSI) with input coming from the 
console terminal performs a temporary implicit UNLOCK. 

For further information on releasing the USR from memory, see the 
.LOCK/.UNLOCK programmed requests (Section 2.45). 

Errors: 

None. 

Example: 



GET READY TO DO MANY USR OPERATIONS 
CALL LOCK IDISABLE USR SWAPPING 
PERFORM THE USR CALLS 



FREE THE USR 
CALL UNLOCK 



3.113 VERIFY 



The VERIFY routine checks that a given string is composed entirely of 
characters from a second string. If a character does not exist in the string 
being examined, VERIFY returns the position of the first character in the 
string being examined that is not in the source string. If all characters 
exist, VERIFY returns a 0. 

Form: CALL VERIFY (a,b,i) 

or 

i = IVERIF(a,b) 

where: 

a is the array containing the string to be scanned; it is terminated 
by a null byte 

b is the array containing the string of characters to be accepted in 
a; it is terminated by a null byte 

Function Result: 

i = If all characters of a exist in b; also if a is a null string. 
= n Where n is the character position of the first character in 
array a that does not appear in array 6; if 6 is a null string 
and a is not, i equals 1. 
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Example: 



The following example accepts a one- to five-digit unsigned decimal 
number and returns its value. 



LaGICAL#l INSTRCai) 



CALL MERIFY( INSTR . '012345G7B9' .1 ) 
IF(I.EO.l) STOP 'NUMBER MISSING' 
IF(I.EO.O) I=LEN(INSTR) 
IF(I.GT.5) STOP 'TOO MANY DIGITS' 
NUM=IMALUE( INSTR .1) 



END 
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Appendix A 
Display File Handler 



This appendix describes the assembly language support provided under 
RT-11 for the VTll graphic display hardware systems. 

The following manuals are suggested for additional reference: 

GT40/GT42 User's Guide 
EK-GT40-OP-002 

GT44 User's Guide 

EK-GT44-OP-001 

VTll Graphic Display Processor 

\ EK-VTll-TM-001 

; 

DECGRAPHIC-11 GT Series Reference Card 
EH-02784-73 

DECGraphic-11 FORTRAN Reference Manual 
DEC-11-GFRMA-A-D 

BASIC-11 Graphics Extensions User's Guide 
DEC-11-LBGEA-A-D 



A.1 Description 



The graphics display terminals have hardware configurations that include a 
display processor and CRT (cathode ray tube) display. All systems are 
equipped with light pens and hardware character and vector generators, and 
are capable of high-quality graphics. The Display File Handler supports this 
graphics hardware at the assembly language level under the RT-11 monitor. 

A.1.1 Assembly Language Display Support 

The Display File Handler is not an RT-11 device handler, since it does not use 
the I/O structure of the RT-11 monitor. For example, it is not possible to use a 
utility program to transfer a text file to the display through the Display File 
Handler. Rather, the Display File Handler provides the graphics programmer 
tiic means lOr tue uispiay oi grapnics iiies anu tiie easy management oi tue 
display processor. Included in its capabilities are such services as interrupt 
handling, light pen support, tracking object, and starting and stopping of the 
display processor. 

The Display File Handler manages the display processor by means of a base 
segment (called VTBASE) which contains interrupt handlers, an internal 
display file and some pointers and flags. The display processor cycles through 
the internal display file; any user graphics files to be displayed are accessed 
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by display subroutine calls from the Handler's display file. In this way, the 
Display File Handler exerts control over the display processor, relieving the 
assembly language user of the task. 

Through the Display File Handler, the programmer can insert and remove 
calls to display files from the Handler's internal display file. Up to two user 
files may be inserted at <^ne time, and that number may be increased by re- 
assembling the Handler. Any user file inserted for display may be blanked 
(the subroutine call to it bypassed) and unblanked by macro calls to the 
Display File Handler. 

Since the Handler treats all user display files as graphics subroutines to its 
internal display file, a display processor subroutine call is loquired. This 
is implemented with software, using the display stop instruction, and 
is available for user programs. This instruction and several other extended 
instructions implemented with the display stop instruction are described in 
Section A. 3. 

The facilities of the Display File Handler are accessed through a file of macro 
definitions (VTMAC) which generate calls to a set of subroutines in VTLIB. 
VTMAC's call protocol is similar to that of the RT-U macros. The expansion 
of the macros is shown in Section A. 6. VTMAC also contains, for convenience 
in programming, the set of recommended display processor instruction 
mnemonics and their values. The mnemonics are listed in Section A. 7 and are 
used in the examples throughout this appendix. 

VTCALl through VTCAL4 are the set of subroutines which service the 
VTMAC calls. They include functions for display file and display processor 
management. These are described in detail in Section A.2. VTCALl through 
VTCAL4 are distributed, along with the base segment VTBASE, as a file of 
five object modules called VTHDLR.OBJ. VTHDLR is built into the graphics 
library VTLIB by using the monitor LIBRARY command. VTHDLR only 
supports VTll hardware. Section A.4.2 shows an example. 

A.1.2 Monitor Display Support 

The RT-11 monitor, under Version 03 and later, directly supports the display 
as a console device. A keyboard monitor command, GT ON (GT OFF) per- 
mits the selection of the display as console device. Selection results in the 
allocation of approximately 1.25K words of memory for text buffer and code. 
The buffer holds approximately 2000 characters. 

The text display includes a blinking cursor to indicate the position in the text 
where a character is added. The cursor initially appears at the top left corner 
of the text area. As lines are added to the text the cursor moves down the 
screen. When the maximum number of lines are on the screen, the top line is 
deleted from the text buffer when the line feed terminating a new line is 
received. This causes the appearance of "scrolling," as the text disappears off 
the top of the display. 

When the maximum number of characters have been inserted in the text 
buffer, the scroller logic deletes a line from the top of the screen to make room 
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for additional characters. Text may appear to move (scroll) off the top of the 
screen while the cursor is in the middle o-f a line. 

The Display File Handler can operate simultaneously with the scroller pro- 
gram, permitting graphic displays and monitor dialogue to appear on the 
screen at the same time. It does this by inserting its internal display file into 
the display processor loop through the text buffer. However, the following 
should be noted. Under the SJ Monitor, if a program using the display for 
graphics is running with the scroller in use (that is, GT ON is in effect), and 
the program does a soft exit (.EXIT with RO not equal to 0) with the display 
stopped, the display remains stopped until a CTRL/C is typed at the key- 
board. 

This can be recognized by failure of the monitor to echo on the screen when 
expected. If the scroller text display disappears after a program exit, always 
type CTRL/C to restore. If CTRL/C fails to restore the display, the running 
program probably has an error. 

Four scroller control characters provide the user with the capability of halting 
the scroller, advancing the scrolling in page sections, and printing hard copy 
from the scroller. 

NOTE 

The scroller logic does not limit the length of a line, but the 
length of text lines affects the number of lines which may be 
displayed, since the text buffer is finite. As text lines become 
longer, the scroller logic may delete extra lines to make room 
for new text, temporarily decreasing the number of lines dis- 
played. 



A. 2 Description of Graphics Macros 

The facilities of the Display File Handler are accessed through a set of macros, 
contained in VTMAC, which generate assembly language calls to the Handler 
at assembly time. The calls take the form of subroutine calls to the sub- 
routines in VTLIB. Arguments are passed to the subroutines through register 
and, in the case of the .TRACK call, through both register and the stack. 

This call convention is similar to Version 1 RT-11 I/O macro calls, except that 
the subroutine call instruction is used instead of the EMT instruction. If a 
macro requires an argument but none is specified, it is assumed that the 
address of the argument has already been piacea m register u. ine prugram- 
mer should not assume that RO is preserved through the call. 

A. 2.1 .BLANK 

The .BLANK request temporarily blanks the user display file specified in the 
request. It does this by bypassing the call to the user display file, which 
prevents the display processor from cycling through the user file, effectively 
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blanking it. This effect can later be canceled by the .RESTR request, which 
restores the user file. When the call returns, the user is assured the display 
processor is not in the file that was blanked. 

Macro Call: .BLANK faddr 

where: 

faddr is the address of the user display file to be blanked 
Errors: 

No error is returned. If the file specified was not found in the Handler 
file or has already been blanked, the request is ignored. 

A.2.2 .CLEAR 

The .CLEAR request initializes the Display File Handler, clearing out any 
calls to user display files and resetting all of the internal flags and pointers. 

After initialization with .LNKRT (Section A.2.4), the .CLEAR request can be 
used any time in a program to clear the display and to reset pointers. All calls 
to user files are deleted and all pointers to status buffers are reset. They must 
be re-inserted if they are to be used again. 

Macro Call: .CLEAR 



Errors: 



None. 



Example: 



This example uses a .CLEAR request to initialize the Handler then 
later uses the .CLEAR to re-initialize the display. The first .CLEAR is 
used for the case when a program may be restarted after a CTRL C or 
other exit. 



BR RSTRT 



EXi: 


BIS #20000»e#44 5SET REENTER BIT IN JSW 


RSTRT : 


.UNLNK 


{CLEARS LINK FLAG FOR RESTART 




♦LNKRT 


fSET UP VECTORS r START DISPLAY 




.CLEAR 


{INITIALIZE HANDLER 




.INSRT #FILE1 


{DISPLAY A PICTURE 


i«: 


.TTYIN 


{WAIT FOR A KEY STRIKE 




CMPB *12,R0 


{LINE FEED? 




BNE 1* 


{NO/ LOOP 




.CLEAR 


?YESr CLEAR DISPLAY 




.INSRT »FILE2 

* 


{DISPLAY NEW PICTURE 


FILEIJ 


* 
« 

POINT 



500 


{AT POINT <0»500) 








LONGV 


{DRAW A LINE 




500IINTX 



riRET 




{TO ( 500 f 500) 
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F1LE2: POINT vAT POINT (500r0) 

500 

LONOy yDRAW A LINE 

oiiNTX rro ( 500 » 500) 

500 

dre:t 



.END EXl 



A.2.3 .INSRT 

The .INSRT request inserts a call to the user display file specified in the 
request into the Display File Handler's internal display file. .INSRT causes 
the display processor to cycle through the user file as a subroutine to the 
internal file. The handler permits two user files at one time. The call inserted 
in the handler looks like the following: 

rUSR > HI SPLAY SUBROUTINE 

.+4 » RETURN ADDRESS 

.f3ddr ^SUBROUTINE ADDRESS 

The call to the user file is removed by replacing its address with the address of 
a null display file. The user file is blanked by replacing the DJSR with a 
DJMP instruction, bypassing the user file. 

Macro Call: .INSRT faddr 

where: 

faddr is the address of the user display file to be inserted 

Errors: 

The .INSRT request returns with the C bit set if there was an error in 
processing the request. An error occurs only when the Handler's display 
file is full and cannot accept another file. If the user file specified exists, 
the request is not processed. Two display files with the same starting 
address cannot be inserted. 

Example: 

See the examples in Sections A. 2. 2 and A. 2. 4. 

A.2.4 .LNKRT 

The .LNKRT request sets up the display interrupt vectors and possibly links 
the Display File Handler to the scroll text buffer in the RT-11 monitor. It 
must be the first call to the Handler, and is used whether or not the RT-11 
monitor is using the display for console output (that is, the KMON command 
GT ON has been entered). 

The .LNKRT request used with Version 03 and later RT-11 monitors enables 
a display application program to determine the environment in which it is 
operating. Error codes are provided for the situations where there is no display 
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hardware present on the system or the display hardware is already being used 
by another task (for example, a foreground job in the foreground/background 
version). 

The existence of the monitor scroller and the size of the Handler's subpicture 
stack are also returned to the caller. If a previous call to .LNKRT was made 
without a subsequent .UNLNK, the .LNKRT call is ignored and an error code 
is returned. 

Macro Call: .LNKRT 

Errors: 

Error codes are returned in RO, with the N condition bit set. 



Code Meaning 

-1 No VTll display hardware is present on this system. 

-2 VTll hardware is presently in use. 

-3 Handler has already been linked. 



On completion of a successful .LNKRT request, RO will contain the 
display subroutine stack size, indicating the depth to which display 
subroutines may be nested. The N bit will be zero. 

If the RT-11 monitor scroll text buffer was not in memory at the time of 
the .LNKRT, the C bit will be returned set. The KMON commands GT 
ON and GT OFF cannot be issued while a task is using the display. 



Example: 



start: 


.LNKRT 




»LINK TO MONITOR 




BMI 


ERROR 


> ERROR DOING LINK 




BCS 


CONT 


»N0 SCROLL IF C SET 




.SCROL 


#SBUF 


5 ADJUST SCROLL PARAMETERS 


cont: 


.INSRT 


♦FILEI 


5 DISPLAY A PICTURE 


1*: 


.TTYIN 




JUAIT FOR KEY STRIKE 




CMPB 


#12fR0 


;line feed? 




BNE 


1* 


5N0r LOOP 




.UNLNK 




fYES» UNLINK AND EXIT 




.EXIT 






sbuf: 


. BYTE 


5 


JLINE COUNT OF 5 




.BYTE 


7 


f INTENSITY 7 (SCALE OF 1-8 




. WORD 


1000 


f POSIT ION OF TOP LINE 


FILEi: 


POINT 

500 

500 




5 AT POINT ( 500 » 500) 




CHAR 




5 DISPLAY SOME TEXT 




.ASCII 


/FILEI THIS 


IS FILEI. TYPE CR TO EXIT/ 




.EVEN 








DRET 







ERROR : 


Error routine 
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A.2.5 .LPEN 

) The .LPEN request transfers the address of a light pen status data buffer to 

VTBASE. Once the buffer pointer has been passed to the Handler, the light 
pen interrupt handler in VTBASE will transfer display processor status data 
to the buffer, depending on the state of the buffer flag. 

The buffer must have seven contiguous words of storage. The first word is the 
buffer flag, and it is initially cleared (set to zero) by the .LPEN request. When 
a light pen interrupt occurs, the interrupt handler transfers status data to the 
buffer and then sets the buffer flag non-zero. The program can loop on the 
buffer flag when waiting for a light pen hit (although doing this will tie up the 
processor; in a foreground/background environment, timed waits would be 
more desirable). No further data transfers take place, despite the occurrence 
of numerous light pen interrupts, until the buffer flag is again cleared to zero. 
This permits the program to process the data before it is destroyed by another 
interrupt. 

i The buffer structure looks like this: 

Buffer Flag 

Name 

Subpicture Tag 

Display Program Counter (DPC) 

Display Status Register (DSR) 

X Status Register (XSR) 

Y Status Register (YSR) 

) 

^' The Name value is the contents of the software Name Register (described in 

A.3.5) at the time of interrupt. The Tag value is the tag of the subpicture 

being displayed at the time of interrupt. The last four data items are the 

contents of the display processor status registers at the time of interrupt. They 

are described in detail in Table A-L 

Macro Call: .LPEN baddr 

\ where; 

baddr is the address of the 7-word light pen status data buffer 
Errors: 

None. 

If a .LPEN was already issued and a buffer specified, the new buffer 
address replaces the previous buffer address. Only one light pen buffer 
can be in use at a time. 

Example: 





.INSRT 


*L..f'Il,..E 


rUlSPLAY LFILE 




. IP EH 


#L.BUF 


fSET UP LPEN BUFFER 


loop; 


TST 


LBUF 


PTEST LBUF FLAGy WHICH 




BEG 


LOOP 


rWILL BE SET NON-ZERO 
?0N LIGHT PEN HIT. 


JPROCES 


i! DATA IN 


LBUP HERE. 
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;DATA in LBUF 




CLR 


LBUF 


; clear the buffer flag 
?i-'ERM]:tting another "hit 




BR 


LOOP 


J GO WAIT FOR IT 


LBUFJ 


.BLKU 


7 


5 SEVEN WORD LPEN BUFFER 


LFII.EJ 









Table A-1: Description of Display Status Words 



Bits 



Significance 



Display Program Counter (DPC=172000) 

0-15 Address of display processor program 

counter at time of interrupt. 

Display Status Register (DSR=172002) 

0-1 Line Type 

2 Spare 

3 Blink 

4 Italics 

5 Edge Indicator 

6 Shift Out 

7 Light Pen Flag 
8-10 Intensity 
11-14 Mode 

15 Stop Flag 



X Status Register (XSR=172004) 

0-9 

10-15 

Y Status Register (YSR=172006) 

0-9 

10-15 



X Position 
Graphplot Increment 

Y Position 
Character Register 



A. 2.6 .NAME 

The .NAME request has been added to the Version 03 and later Display File 
Handler. The contents of the name register are now stacked when a subpic- 
ture call is made. When a light pen interrupt occurs, the contents of the name 
register stack may be recovered if the user program has supplied the address 
of a buffer through the .NAME request. 

The buffer must have a size equal to the stack depth (default is 10) plus one 

vvv^j.vu. x\jx uiio xxdg* T T iioix bxxc^ .xix^xTXjjj xcv^ucou lo cii i/Cj. c;\a ^ uxic ai^u.ic;oo \JL VXl^ 

buffer is passed to the Handler and the first word (the flag word) is cleared. 
When a light pen hit occurs, the stack's contents are transferred and the flag 
is set non-zero. 

Macro Call: .NAME baddr 



where: 



baddr is the address of the name register buffer 
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Errors: 

None. 

If a .NAME request has been previously issued, the new buffer address 
replaces the previous buffer address. 

A. 2.7 .REMOV 

The .REMOV request removes the call to a user display file previously in- 
serted in the handler's display file by the .INSRT request. All reference to the 
user file is removed, unlike the .BLANK request, which merely bypasses the 
call while leaving it intact. 

Macro Call: .REMOV faddr 

where: 

faddr is the address of the display file to be removed 

Errors: 

No errors are returned. If the file address given cannot be found, the 
request is ignored. 

A.2.8 .RESTR 

The .RESTR request restores a user display file that was previously blanked 
by a .BLANK request. It removes the by-pass of the call to the user file, so 
that the display processor once again cycles through the user file. 

Macro Call: .RESTR faddr 

where: 

faddr is the address of the user file that is to be restored to view 

Errors: 

No errors are returned. If the file specified cannot be found, the request 
is ignored. 

A.2.9 .SCROL 

This request is used to modify the appearance of the Display Monitor's text 
display. The .SCROL request permits the programmer to change the maxi- 
mum line count, intensity and the position of the top line of text of the 
scroller. The request passes the address of a two-word buffer which contains 
the parameter specifications. The first byte is the line count, the second byte 
is the intensity, and the second word is the Y position. Line count, intensity 
and Y position must all be octal numbers. The intensity may be any number 
from to 7, ranging from dimmest to brightest. (If an intensity of is speci- 
fied, the scroller text will be almost unnoticeable at a BRIGHTNESS knob 
setting less than one-half.) The scroller parameter change is temporary, since 
an .UNLNK or CTRL/C restores the previous values. 
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Macro Call: .SCROL baddr 



where: 



baddr is the address of the two-word scroll parameters buffer 



Errors: 



No errors are returned. No checking is done on the values of the param- 
eters. A zero argument is interpreted to mean that the parameter value 
is not to be changed. A negative argument causes the default parameter 
value to be restored. 



Example: 



. SCROL 



♦SCBUF 



? ADJUST SCROLL, PARAMETERS 



SCBUF 5 



.BYTE 5 
♦BYTE 
♦WORD 300 



» DECREASE *LINES TO 5. 
JLEAVE INTENSITY UNCHANGED. 
fTOP LINE AT Y=300. 



A.2.10 .START 

The .START request starts the display processor if it was stopped by a .STOP 
directive. If the display processor is running, it is stopped first, then restarted. 
In either case, the subpicture stack is cleared and the display processor is 
started at the top of the handler's internal display file. 

Macro Call: .START 

Errors: 

None. 

A.2.11 .STAT 

The .STAT request transfers the address of a seven-word status buffer to the 
display stop interrupt routine in VTBASE. Once the transfer has been made, 
display processor status data is transferred to the buffer by the display stop 
interrupt routine in VTBASE whenever a .DSTAT or .DHALT instruction is 
encountered (see Sections A.3.3 and A.3.4). The transfer is made only when 
the buffer flag is clear (zero). After the transfer is made, the buffer flag is set 
non-zero and the .DSTAT or .DHALT instruction is replaced by a .DNOP 
(Display NOP) instruction. 

'I'he status buffer must be a seven-word, contiguous block of memory. Its 
contents are the same as the light pen status buffer. For a detailed description 
of the buffer and an explanation of the status words, see Section A. 2.5 and 
Table A-1. 

Macro Call: .STAT baddr 

where: 

baddr is the address of the status buffer receiving the data 
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Errors: 

No errors are indicated. If a buffer was previously set up, the new buffer 
address is replaced as the old buffer address. 

A.2.12 .STOP 

The .STOP request "stops" the display processor. It actually effects a stop by 
preventing the DPU from cycling through any user display files. It is useful for 
stopping the display during modification of a display file, a risky task when 
the display processor is running. However, a .BLANK could be equally useful 
for this purpose, since the .BLANK request does not return until the display 
processor has been removed from the user display file being blanked. 

Macro Call: .STOP 

Errors: 

None. 

NOTE 

Since the display processor must cycle through the text buffer 
in the Display Monitor in order for console output to be pro- 
cessed, the text buffer remains visible after a .STOP request is 
processed, but all user files disappear. 

A.2.13 .SYNC/.NOSYN 

The .SYNC and .NOSYN requests provide program access to the power line 
synchronization feature of the display processor. The .SYNC request enables 
synchronization and the .NOSYN request disables it (the default case). 

Synchronization is achieved by stopping the display and restarting it when 
the power line frequency reaches a trigger point, e.g., a peak or zero- crossing. 
Synchronization has the effect of fixing the display refresh time. This may be 
useful in some cases where small amounts of material are displayed but the 
amount frequently changes, causing changes in intensity. In most cases, how- 
ever, using synchronization increases flicker. 

Macro Calls: .SYNC 
.NOSYN 

Errors: 

None. 

A.2.14 .TRACK 

The .TRACK request causes the tracking object to appear on the display CRT 
at the position specified in the request. The tracking object is a diamond- 
shaped display figure which is light-pen sensitive. If the light pen is placed 
over the tracking object and then moved, the tracking object follows the light 
pen, trying to center itself on the pen. 
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The tracking object first appears at a position specified in a two-word buffer 
whose address was supplied with the .TRACK request. As the tracking object 
moves to keep centered on the light pen, the new center position is returned 
to the buffer. A new set of X and Y values is returned for each light pen 
interrupt. 

The tracking object cannot be lost by moving it off the visible portion of the 
display CRT. When the edge flag is set, indicating a side of the tracking object 
is crossing the edge of the display area, the tracking object stops until moved 
toward the center. To remove the tracking object from the screen, repeat the 
.TRACK request without arguments. 

The .TRACK request may also include the address of a completion routine as 
the second argument. If a .TRACK completion routine is specified, the light 
pen interrupt handler passes control to the completion routine at interrupt 
level. The completion routine is called as a subroutine and the exit statement 
must be an RTS PC. The completion routine must also preserve any registers 
it may use. 

Macro Call: .TRACK baddr, croutine 

where: 

baddr is the address of the two-word buffer containing the X and Y 
position for the track object 

croutine is the address of the completion routine 

Errors: 

None. 

Example: 

See Section A.IO. 

A.2.15 .UNLNK 

The .UNLNK request is used before exiting from a program. In the case where 
the scroller is present, .UNLNK breaks the link, established by .LNKRT, 
between the Display File Handler's internal display file and the scroll file in 
the Display Monitor. The display processor is started cycling in the scroll text 
buffer, and no further graphics may be done until the link is established 
again. In the case where no scroller exists, the display processor is simply left 
stopped. 

Macro Call: .UNLNK 

Errors: 

No errors are returned. An internal link flag is checked to determine if 
the link exists. If it does not exist, the request is ignored. 
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A. 3 Extended Display Instructions 

The Display File Handler offers the assembly language graphics programmer 
an extended display processor instruction set, implemented in software 
through the use of the Load Status Register A (LSRA) instruction. The ex- 
tended instruction set includes: subroutine call, subroutine return, display 
status return, display halt, and load name register. 

A. 3.1 DJSR Subroutine Call Instruction 

The DJSR instruction (octal code is 173400) simulates a display subroutine 
call instruction by using the display stop instruction (LSRA instruction with 
interrupt bits set). The display stop interrupt handler interprets the non-zero 
word following the DJSR as the subroutine return address, and the second 
word following the DJSR as the address of the subroutine to be called. The 
instruction sequence is: 

DJSR 

Return address 

Subroutine address 

Example: 

To call a subroutine SQUARE: 



POINT 


^POSITION BEAM 


100 


»AT (lOOrlOO) 


100 




DJSR 


JTHEN CALL SUBROUTINE: 


.+4 




SQUARE 


5 TO DRAW A SQUARE 


DRET 










The use of the return address preceding the subroutine address offers 
several advantages. For example, the BASIC-11 graphics software uses 
the return address to branch around subpicture tag data stored follow- 
ing the subpicture address. This structure is described in Section A. 5. 3. 
In addition, a subroutine may be temporarily bypassed by replacing the 
DJSR code with a DJMP instruction, without the need to stop the 
display processor to make the by-pass. 

The address of the return address is stacked by the display stop inter- 
rupt handler on an internal subpicture stack. The stack depth is condi- 
tionalized and has a default depth of 10. If the stack bottom is reached, 
the display stop interrupt handler attempts to protect the system by 
rejectmg auuitionai suuroutine caiis. in tiiat case, tue portions oi tue 
display exceeding the legal stack depth will not be displayed. 

A. 3. 2 DRET Subroutine Return Instruction 

The DRET instruction provides the means for returning from a display file 
subroutine. It uses the same octal code as DJSR, but with a single argument 
of zero. The DRET instruction causes the display stop interrupt handler to 
pop its subpicture stack and fetch the subroutine return address. 
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Example: 



square: longv 

lOOIINTX 



O'lNTX 

100 

lOOIINTXIMINUSX 



OIINTX 

lOOIMINUSX 

riRET 





J DRAW A SQUARE 



; RETURN FROM SUBPICTURE 



A. 3.3 DSTAT Display Status Instruction 

The DSTAT instruction (octal code is 173420) uses the LSRA instruction to 
produce a display stop interrupt, causing the display stop interrupt handler to 
return display status data to a seven-word user status buffer. The status 
buffer must first have been set up w^ith a .STAT macro call (if not, the 
DSTAT is ignored and the display is resumed). The first word of the buffer is 
set non-zero to indicate the transfer has taken place, and the DSTAT is 
replaced with a DNOP (display NOP). The first word is the buffer flag and 
the next six words contain name register contents, current subpicture tag, 
display program counter, display status register, display X register, and dis- 
play Y register. After transfer of status data, the display is resumed. 

A.3.4 DHALT Display Halt Instruction 

The DHALT instruction (octal code is 173500) operates similarly to the 
DSTAT instruction. The difference between the two instructions is that the 
DHALT instruction leaves the display processor stopped when exiting from 
the interrupt. A status data transfer takes place provided the buffer was 
initialized with a .STAT call. If not, the DHALT is ignored. 

Example: 



Hi 



.STAT tSBUF 

MOV #IiHALT,STPLOC 

.INSRT #riFILE 

TST SBUF 

BEQ 1* 



fINIT BUFFER 
y INSERT DHALT 
rniSPLAY THE PICTURE 
5 DHALT PROCESSED? 
im, WAIT 



SBUF J 

dfile: 



STPLOCJ 



.BLKU 7 

POINT 

.WORD 

LONGV 

.WORD 

DNOP 

DRET 





500»1350 
0t400 



» STATUS BUFFER 
5 POSITION NEAR 



TOP OF 12" TUBE 



JDRAW A LINE, MAYBE OVER EDGE 
fIF IT IS A 12= SCOPE. 
J STATUS IdlLL BE RETURNED AT 
5THIS POINT 



A. 3. 5 DNAME Load Name Register Instruction 

The Display File Handler provides a name register capability through the use 
of the display stop interrupt. When a DNAME instruction (octal code is 
173520) is encountered, a display stop interrupt is generated. The display stop 
handler stores the argument following the DNAME instruction in an internal 
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software register called the "name register." The current name register con- 
tents are returned whenever a DSTAT or DHALT is encountered, and more 
importantly, whenever a light pen interrupt occurs. The use of a "name" 
(with a valid range from 1 to 77777) enables the programmer to label each 
element of the display file with a unique name, permitting the easy identifica- 
tion of the particular display element selected by the light pen. 

The name register contents are stacked on a subpicture call and restored on 
return from the subpicture. 

Example: 

The SQUARE subroutine with "named" sides. 



square: dname jname is 

10 flO 

LONGV fDRAW A SIDE 

lOOIINTX 



DNAME J THIS SIDE IS NAMED 

11 fll 

OIINTX 5 STILL IS LONG VECTOR MODE 

100 

DNAME 

12 

lOOIINTXIMINUSX 



DNAME 

13 

OIINTX 

lOOIMINUSX 

DRET f RETURN FROM SUBPICTURE 





A. 4 Using the Display File Handler 

Graphics programs which intend to use the Display File Handler for display 
processor management can be written in MACRO assembly language. The 
display code portions of the program may use the mnemonics described in 
Section A. 7. Calls to the Handler should have the format described in 
Section A. 6. 

The Display File Handler is supplied in two pieces, a file of MACRO defini- 
tions and a library containing the Display File Handler modules. 

MACRO Definition File: VTMAC.MAC 

Display File Handler: VTLIB.OBJ (consisting of:) 

VTBASE.OBJ 
VTCALl.OBJ 
VTCAL2.0BJ 
VTCAL3.0BJ 
VTCAL4.0BJ 
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A. 4.1 Assembling Graphics Programs 

To assemble a graphics program using the display processor mnemonics or the 
Display Handler macro calls, the file VTMAC.MAC must be assembled with 
the program, and must precede the program in the assembler command 
string. 

Example: 

Assume PICTUR.MAC is a user graphics program to be assembled. An 
assembler command string would look like this: 
MACRO VTMAC+PICTUR/OBJECT 

A. 4. 2 Linlcing Graphics Programs 

Once assembled with VTMAC, the graphics program must be linked with the 
Display File Handler, which is supplied as a single concatenated object mod- 
ule, VTHDLR.OBJ. The Handler may optionally be built as a library, follow- 
ing the directions in A.8.5. The advantage of using the library when linking is 
that the Linker will select from the library only those modules actually used. 
Linking with VTHDLR.OBJ results in all modules being included in the link. 

To link a user program called PICTUR.OBJ using the concatenated object 
module supplied with RT-11: 

LINK PICTUR»VTHIiLR 

To link a program called PICTUR.OBJ using the VTLIB library built by 
following the directions in A.8.5, be sure to use the Version 03 Linker: 
LINK PICTUR»VTLIB 



VTLIB (Handler Modules): 

Module CSECT Contains 



Globals 



VTCALl 


$GT1 


.CLEAR 


$VINIT 






.START 


$VSTRT 




.STOP 


IVSTOF 








.INSRT 


$VNSRT 






.REMOV 


$VRMOV 


VTCAL2 


$GT2 


.BLANK 


$VBLNK 






.RESTR 


$VRSTR 


VTCAL3 


$GT3 


.LPEN 


$VLPEN 






-NAME 


$NAME 






.STAT 


$VSTPM 






.SYNC 


$SYNC 






.NOSYN 


$NOSYN 






.TRACK 


IVTRAK 


VTCAL4 


$GT4 


.LNKRT 


$VRTLK 






.UNLNK 


$VUNLK 






.SCROL 


IVSCRL 


VTBASE 


$GTB 


Interrupt handlers 
and internal 
display file 


$DFILE 
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The file modules in VTHDLR can be used in three different ways. When space 
is not critical, the most straightforward way is to link VTHDLR directly with 
a display program. The following command is an example. 

LINK PICTURryTHDLR 

It is often necessary to conserve space, however, and selective loading of 
modules is possible by first creating an indexed object module library from 
VTHDLR and then by making global calls within the display program. The 
following command creates an indexed object module library. 

LIBRARY/CREATE VTLIB VTHDLR 

To further conserve space with overlays, it is also possible to extract individ- 
ual object modules from a library and create separate object module files. For 
example, to link a display program using overlays, the following statements 
are a typical sequence of creating, extracting and linking commands. (NOTE: 
the modules VTCALl and VTCAL2 must be in the same overlay if any global 
in either one is used.) 



.LIBRARY/CREATE VTLIB yTHDLR 



.LIBRARY/EXTRACT UTLIB MTCALl 

GLOBAL? $VSTRT ! moves entire module with $VSTRT to VTCALl 

GLOBAL? ! Terminates FromptinS seouence 

.LIBRARY/EXTRACT VTLIB VTCAL2 

GLOBAL? $VBLNK ! Moves the entire module to VTCAL2 

GLOBAL? 

.LIBRARY/EXTRACT VTLIB VTCAL3 

GLOBAL? «VLPEN ! Moves the entire module 

GLOBAL? 

.LIBRARY/EXTRACT VTLIB VTCAL4 

GLOBAL? *VRTLK ! Moves the entire module 

GLOBAL? 

.LIBRARY/EXTRACT VTLIB VTBASE 

GLOBAL? *DFILE ! Moves the entire module 

GLOBAL? 



.LINK/PROMPT PICTUR.VTBASE 
*VTCAL1 rVTCAL2»VTCAL3/0: 1 
*VTCAL4/0:i 
*// 



A. 5 Display File Structure 



The Display File Handler supports a variety of display file structures, takes 
over the job of display processor management for the programmer, and may 
be used for both assembly language graphics programming and for systems 
program development. For example, the Handler supports the tagged subpic- 
ture file structure used by the BASIC-11 graphics software, as well as simple 
file structures. These are discussed in this section. 
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A. 5.1 Subroutine Calls 

A subroutine call instruction, with the mnemonic DJSR, is implemented us- ) 

ing the display stop (DSTOP) instruction with an interrupt. The display stop 
interrupt routine in the Display File Handler simulates the DJSR instruction, 
and this allows great flexibility in choosing the characteristics of the DJSR 
instruction. 

The DJSR instruction stops the display processor and requests an interrupt. 
The DJSR instruction may be followed by two or more words, and in this 
implementation the exact number may be varied by the programmer at any 
time. The basic subroutine call has this form: 

DJSR 

Return Address 

Subroutine Address 

In practice, simple calls to subroutines could look like: 

DJSR 

.WORD .+4 I 

. WORD SUB 

where SUB is the address of the subroutine. Control will return to the display 
instruction following the last word of the subroutine call. This structure per- 
mits a call to the subroutine to be easily by-passed without stopping the 
display processor, by replacing the DJSR with a display jump (DJMP) in- 
struction: 

ruMP 

.WORD .+4 ) 

. WORD SUB 

A more complex display file structure is possible if the return address is 
generalized: 

. DJSR 

.WORD NEXT 

. WORD SUB 

where NEXT is the generalized return address. This is equivalent to the 
sequence: 

DJSR 

.WORD .+4 

.WORD SUB 

DJMP 

.WORD NEXT 

It is also possible to store non-graphic data such as tags and pointers in the 
subroutine call sequence, such as is done in the tagged subpicture display file 
structure of the BASIC-11 graphics software. This technique looks like: 

DJSR 

.WORD NEXT 



.WORD SUB 
DATA 



next; 



For simple applications where the flexibility of the DJSR instruction de- 
scribed above is not needed and the resultant overhead is not desired, the 
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Display File Handler (VTBASE.MAC and VTCALL.MAC) can be condition- 
ally re-assembled to produce a simple DJSR call. If NOTAG is defined during 
the assembly, the Handler will be configured to support this simple DJSR 
call: 



DJSR 
. WORD 



SUB 



where SUB is the address of the subroutine. Defining NOTAG will eliminate 
the subpicture tag capability, and with it the tracking object, which uses the 
tag feature to identify itself to the light pen interrupt handler. 

Whatever the DJSR format used, all subroutines and the user main file must 
be terminated with a subroutine return instruction. This is implemented as a 
display stop instruction (given the mnemonic DRET) with an argument of 
zero. A subroutine then has the form: 

sub: Displau Code 
DRET 
.WORD 



A. 5. 2 Main File/Subroutine Structure 

A common method of structuring display files is to have a main file which 
calls a series of display subroutines. Each subroutine will produce a picture 
element and may be called many times to build up a picture, producing 
economy of code. If the following macros are defined: 



.MACRO 


CALL <ARG 


DJSR 
. WORD 


.+4 


.WORD 


ARG 


.ENDM 




.MACRO 


RETURN 


DRET 




. WORD 





.ENDM 





then a main file/subroutine file structure would look like: 
jMain display file 



main: 


DisF-law Code 






CALL SUBI 
Display Code 
CALL SUB2 

♦ 


fCALL SUBROUTINE 1 

5CALL SUBROUTINE 2 
5 ETC 




• 

RETURN 




; DISPLAY 


SUBROUTINES 




suBi: 


Display Code 
RETURN 


{SUBROUTINE 1 


f 

SUB2: 


Display Code 
RETURN 


» SUBROUTINE 2 




♦ 


J ETC. 
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A.5.3 BASIC-11 Graphic Software Subroutine Structure 

An example of another method of structuring display files is the tagged sub- 
picture structure used by BASIC-11 graphic software. The display file is 
divided into distinguishable elements called subpictures, each of which has its 
own unique tag. 

The subpicture is constructed as a subroutine call followed by the subroutine. 
It is essentially a merger of the main file/subroutine structure into an in-line 
sequence of calls and subroutines. As such, it facilitates the construction of 
display files in real time, one of the important advantages of BASIC-11 
graphic software. 

The following is an example of the subpicture structure. Each subpicture has 
a call to a subroutine with the return address set to be the address of the next 
subpicture. The subroutine called may either immediately follow the call, or 
may be a subroutine defined as part of a subpicture created earlier in the 
display file. This permits a subroutine to be used by several subpictures 
without duplication of code. Each subpicture has a tag to identify it, and it is 
this tag which is returned by the light pen interrupt routine. To facilitate 
finding subpictures in the display file, they are made into a linked list by 
inserting a forward pointer to the next tag. 

SUBi: DJSR JSTART OF SUBPICTURE 1 

.WORD SUB2 5NEXT SUBPICTURE 

.WORD SUBl+12 f JUMP TO THIS SUBPICTURE 

.WORD 1 J TAG = 1 

.WORD SUB2+A fPOINTER TO NEXT TAG 

rBODY OF SUBPICTURE 1 



BRET 


SUB2 : DJSR 
.WORD 
.WORD 
.UORIi 
.UORD 

JBOriY OF SUBPICTURE 



SUB3 
SUB2+12 

SUB3+6 



f RETURN FROM 
5 SUBPICTURE 1 

; START SUBPICTURE 2 

fNEXT SUBPICTURE 

5 JUMP TO THIS SUBPICTURE 

fTAG 2 

rPTR TO NEXT TAG 



SUB3J 



SUB4: 



BRET 
, UORD 

DJSR 
. WORD 
. UORD 

. WORD 
. WORD 

DJSR 



SUB4 
SUBl+12 



SUB4+6 



J RETURN FROM 
5 SUBPICTURE 2 

r START SUBPICTURE 3 
5 NEXT SUBPICTURE 
fCOPY SUBPICTURE 1 
rFOR THIS SUBPICTURE 
?BUT TAG IT 3. 
JPTR TO NEXT TAG 

f START SUBPICTURE 4 
fETC. 
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A.6 Summary of Graphics MACRO Calls 









Assembly Language 






MACRO Call 


Expansion 


Mnemonic 


Function 


(see Note 1) 


(see Note 2) 


.BLANK 


Temporarily blanks 


.BLANK faddr 


.GLOBL $VBLNK 




a user display file. 




.IF NB, faddr 

MOV faddr, "100 

.ENDC 

JSR -07, $VBLNK 


.CLEAR 


Initializes handler. 


.CLEAR 


.GLOBL $VINIT 
JSR -07, $VINIT 


.INSRT 


Inserts a call to 


.INSRT faddr 


.GLOBL $VNSRT 




user display file 




.IF NB, faddr 




in handler's master 




MOV faddr, "OO 




display file. 




.ENDC 

JSR "07, $VNSRT 


.LNKRT 


Sets up vectors and 


.LNKRT 


.GLOBL $VRTLK 




links display file 




JSR "07, $VRTLK 




handler to RT-U 








scroller. 






.LPEN 


Sets up light pen 


.LPEN baddr 


.GLOBL $VLPEN 




status buffer. 




.IF NB, baddr 
MOV baddr, "OO 
.ENDC 

JSR "07, $VLPEN 


.NAME 


Sets up buffer to 


.NAME \baddr 


.GLOBL $NAME 




receive name 




.IF NB, baddr 




register stack 




MOV .BEDDR, "OO 




contents. 




.ENDC 

JSR "07, $NAME 


.NOSYN 


Disables power line 


.NOSYN 


.GLOBL $NOSYN 




synchronization. 




JSR "07, $NOSYN 


.REMOV 


Removes the call to 


.REMOV faddr 


.GLOBL $VRMOV 




a user display file. 




.IF NB, faddr 

MOV faddr, "OO 

.ENDC 

JSR "07, $VRMOV 


.RESTR 


Unblanks the user 


.RESTR faddr 


.GLOBL $VRSTR 




display file. 




IF NB, faddr 

MOV faddr, "OO 

ENDC 

JSR "07, $VRSTR 


.SCROL 


Adjusts monitor 


.SCROL baddr 


.GLOBL $VSCRL 




scroller parameters. 




.IF NB, baddr 

MOV baddr, "OO 

.ENDC 

JSR "07, $VSCRL 
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Mnemonic 



Function 



.START Starts the display. 



.STAT 



.SYNC 



.TRACK 



.UNLNK 



MACRO Call 
(see Note 1) 

.START 



Assembly Language 

Expansion 

(see Note 2) 

.GLOBL $VSTRT 
JSR -07, $VSTRT 



Sets up status 


.STAT baddr 


.GLOBL $VSTPM 


buffer. 




.IF NB, baddr 

MOV baddr, "OO 

.ENDC 

JSR "07, $VSTPM 


Stops the display. 


.STOP 


.GLOBL $VSTOP 
JSR "07, $VSTOP 


Enables power line 


.SYNC 


.GLOBL $SYNC 


synchronization. 




JSR "07, $SYNC 


Enables the track 


.TRACK baddr, 


.GLOBL $VTRAK 


object. 


croutine 


IF NB, baddr 

MOV baddr, "00 

.ENDC 

.IF NB, croutine 

MOV croutine,- 

('06) 

.IFF 

CLR-('06) 

.ENDC 

.NARG T 

.IF EQ, T 

CLR "OO 

.ENDC 

JSR "07, $VTRAK 


Unlinks display 


.UNLNK 


.GLOBL $VUNLK 


handler from RT-U 




JSR "07, IVUNLK 



if linked (otherwise 
leaves display stopped). 



NOTE 1 
baddr Address of data buffer, 
faddr Address of start of user display file, 

croutine Address of .TRACK completion routine. 

NOTE 2 

The lines preceded by a dot will not be assembled. 
The code they enclose may or may not be assembled 
depending on the conditionals. 
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A. 7 Display Processor Mnemonics 



Mnemonic 


Value 


Function 


CHAR 


100000 


Character Mode 


SHORTY 


104000 


Short Vector Mode 


LONGV 


110000 


Long Vector Mode 


POINT 


114000 


Point Mode 


GRAPHX 


120000 


(Jraphplot X Mode 


GRAPHY 


124000 


Graphplot Y Mode 


RELATV 


130000 


Relative Point Mode 


INTO 


2000 


Intensity (Dim) 


INTl 


2200 


Intensity 1 


INT2 


2400 


Intensity 2 


INT3 


2600 


Intensity 3 


INT4 


;«)()() 


Intensity 4 


INT5 


3200 


Intensity 5 


INT6 


15400 


Intensity 6 


INT7 


3600 


Intensity 7 (Bright) 


LPOFF 


100 


Light Pen Off 


LPON 


140 


Light Pen On 


BLKOFF 


20 


Blink Off 


BLKON 


30 


Blink On 


LINEO 


4 


Solid Line 


LINEl 


5 


Long Dash 


LINE2 


6 


Short Dash 


LINES 


7 


Dot Dash 


DJMP 


160000 


Display Jump 


DNOP 


164000 


Display No Operation 


STATSA 


170000 


Load Status A 
Instruction 


LPLITE 


200 


Light Pen Hit On 


LPDARK 


300 


Light Pen Hit Off 


ITALO 


40 


Italics Off 


ITALl 


60 


Italics On 


SYNC- 


4 


Halt and Resume 
Synchronized 


STATS B 


174000 


Load Status B 
Instruction 



INCH 



100 



Graphplot Increment 



Vector/Point Mode 
INTX 

MAXX 
MAXY 

MINUSX 
MINUSY 



40000 Intensity Vector or 

Point 

1777 Maximum X Component 

1377 Maximum Y Component 

20000 Negative X Component 

20000 Negative Y Component 
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JVlnemonic 




Value 


Short Vector Mode 




SHIFTX 


= 


200 


MAXSX 


= 


17600 


MAXSY 


= 


77 


MISVX 


= 


20000 


MISVY 


= 


100 



Function 



Maximum X Component 
Maximum Y Component 

Negative X Component 
Negative Y Component 



A. 8 Assembly Instructions 

A. 8.1 General Instructions 

All programs can be assembled in 16K, using RT-11 MACRO. All assemblies 
and all links should be error free. The following conventions are assumed: 

1. Default file types are not explicitly typed. These are .MAC for source files, 
.OBJ for assembler output, and .SAV for Linker output. 

2. The default device (DK) is used for all files in the example command 
strings. 

3. Listings and link maps are not generated in the example command 
strings. 



A.8.2 VTBASE 

To assemble VTBASE with RT-11 link-up capability. 

MACRO VTBASE 

A.8.3 VTCAL1 - VTCAL4 

To assemble the modules VTCALl through VTCAL4: 

MACRO VTCALl . UTCAL2 , VTCAL3 , VTCAL4 

A.8.4 VTHDLR 

To create the concatenated handler module: 

COPY/BINARY VTCALl . OBJ » VTCAL2 . OBJ t VTCAL3 . OBJ , • 
VTCAL4 . OBJ , VTBASE . OBJ VTHBLR . OBJ 



A.8.5 Building VTLiB.OBJ 

To build the VTLIB library: 

LIBRARY/CREATE VTLIB VTHDLR 
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A.9 VTMAC 



.TITLE VTMAC 
f THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY ONLY BE USED 
r OR COPIED IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE. 
i 
f COPYRIGHT <C) 1978» DIGITAL EQUIPMENT CORPORATION. 



} VTMAC IS A LIBRARY OF MACRO CALLS AND MNEMONIC DEFINITIIONS WHICH 
i PROVIDE SUPPORT OF THE VTll DISPLAY PROCESSOR. THE MACROS PRODUCE 
r CALLS TO THE VTll DEVICE SUPPORT PACKAGE » USiNG GLOBAL REFERENCES. 

} MACRO TO GENERATE A MACRO WITH ZERO ARGUMENTS. 
.MACRO MACO NAME » CALL 

.MACRO NAME 

.GLOBL CALL 
JSR PC » CALL 

.ENDM 
.ENDM 

f MACRO TO GENERATE A MACRO WITH ONE ARGUMENT 

.MACRO MACl NAME, CALL 

.MACRO NAME ARG 

.IF NBfARG 

MOV ARG»%"00 

.ENDC 

.GLOBL CALL 

JSR PC y CALL 

.ENDM 
.ENDM 

; MACRO TO GENERATE A MACRO WITH TWO OPTIONAL ARGUMENTS 

.MACRO MAC2 NAME, CALL 

.MACRO NAME ARG1»AR62 
.GLOBL CALL 
.IF NBfARGl 



.ENDM 



MOV ARG1,%"00 

. ENDC 

.IF NBfARG2 

MOV ARG2f-<SP) 

.IFF 

CLR -(SP> 

.NARG T 

.IF EQ,T 

CLR %"00 

. ENDC 

. ENDC 

JSR PC » CALL 

.ENDM 



f MACRO LIBRARY FOR VTll; 



MACO 


< . CLEAR> 


,<*vinit: 


MACO 


<.STOP>, 


<*VSTOP> 


MACO 


<.START> 


■»<$vstrt: 


MACl 


<.INSRT> 


,<*VNSRT 


MACl 


<.REMOV> 


■,<*VRMOV 


MACl 


< . blank::: 


• f <*VBLNK 


MACl 


<.RESTR> 


r<*VRSTR: 


MACl 


<.STAT>» 


<*vstpm> 


MACl 


<.LPEN>» 


<*VLPEN> 



Display File Handler A-25 



MACl 
MAC2 
MACO 
MACO 



: . SCROL> 
: . TRACK> 
:.LNKRT> 
:.UNLNK> 



<«VTRAK> 
<*yRTL.K> 
<*UUNL.K> 



MNEMONIC DEFINITIONS FOR THE VTli DISPLAY PROCESSOR 



DJMP= 160000 
DN0P=164000 
DJSR= 173400 
DRET= 173400 
DNAME= 173520 
DSTAT= 173420 
DHALT=173500 



; DISPLAY JUMP 

f DISPLAY NOP 

5 DISPLAY SUBROUTINE CALL 

; DISPLAY SUBROUTINE RETURN 

fSET NAME REGISTER 

! RETURN STATUS DATA 

;STOP DISPLAY AND RETURN STATUS DATA 



CHAR= 100000 

SH0RTV=104000 

L0NGV=1 10000 

P0INT=114000 

GRAPHX:= 120000 

GRAPHY=--124000 

RELATV=130000 



J CHARACTER -MODE 

; SHORT VECTOR MODE 

rLONG VECTOR MODE 

» POINT MODE 

5 GRAPH X MODE 

r GRAPH Y MODE 

; RELATIVE VECTOR MODE 



INTO= 
INT1 = 
I NT 2 = 
INT3= 
INT4= 
INT5= 
INT6= 
INT7= 



2000 
2200 
2400 
2600 
3000 
3200 
3400 
3600 



INTENSITY 



LP0FF=100 

LP0N=140 

BLK0FF=20 

BLK0N=30 

LINE0=4 

LINE1=5 

LINE2=6 

LINE3=7 

STATSA=170000 

LPLITE=200 

LPDARK=300 

ITAL0=40 

ITAL1=60 

SYNC=4 

STATSB=174000 

INCR=100 

INTX=40000 

MAXX=1777 

MAXY=1377 

MINUSX=20000 

MINUSY=20000 

MAXSX=17600 

MAXSY=77 

MISVX=20000 

MISVY=100 



LIGHT PEN OFF 
LIGHT PEN ON 
BLINK OFF 
BLINK ON 
SOLID LINE 
LONG DASH 
SHORT DASH 
DOT DASH 

LOAD STATUS REG A 
INTENSIFY ON LPEN HIT 
DON'T INTENSIFY 
ITALICS OFF 
ITALICS ON 
POWER LINE SYNC 

LOAD STATUS REG B 
GRAPH PLOT INCREMENT 
INTENSIFY VECTOR OR POINT 
MAXIMUM X I NCR. ~ LONGV 
MAXIMUM Y INCR. = LONGV 
NEGATIVE X INCREMENT 
NEGATIVE Y INCREMENT 
MAXIMUM X INCR. ~ SHORTV 
MAXIMUM Y INCR. = SHORTV 
NEGATIVE X INCR. = SHORTV 
NEGATIVE Y INCR. = SHORTV 



A-26 Display File Handler 



UJ 







13 






























o 










o 


»-• 
















»-* 




















UI 










o 






QC 




t- 


X 






or 










o^ -I 












aj 








_i a: 










o 






1- 












Q 


■X 








X 












LS 








•-1 Ul a 






p- 










a. 




ta 


a 






»— 


Ul 








t- UJ 












< 








u. u. .-T 






►- 




CO 






a t-f 


Ul 


■4 


_» 






i-t 


u. 








i 








o 




CK W 








u. •- 






^ 




:^ 


o 




_J 


o 


_J 






a 


2 


u. 








o »- 








i 




o c- <o 








>- r> 1- 


«^ 




a 




■^ O Ul 


TC 




Xi O 


o 


U. 


a: 




Ul 


a 


3 








■i. 








o 




►- a Ul 




_J 




•« U 1- 


t— 




Ji 




•-* !-♦ ^ 


t- 




■^ ►- 


CJ 




Ul 




X 


X 


ID 








< X 








» 




►-« O J- 




_1 




_i 


►-• 




»-H 




< >• _J Ul 




X 


>- 2 




oc 


X 




»— 












t- 












z. ct 




O 




Q. ii IT. 


X 








CJ Ul •« 2 


> 


UJ 


O •-< 


t- 


UI 


»- 




o 


X 


CO 








rt •-I 








Ifl 




o a: »- 




;»-. 




CO UJ o 






f— 




•« -r >■ o 


ID 


o 




< 


tl. 


a 


2 t«» 


2 


o 


3 








UJ X 








3 




3L UJ ^ 


a 


u 




•-■ Q. U. 


■2 




1— 


►— 


a. 




2 


Ul a: 


X 


u. 


2 


M O 


■a. 


a 


►- 








u. 








•— 




»-• 


»- «/3 




O _l 


UJ 






»-r 


OL Ul 1- 


>- 


»-* 


_l o 


t- 


3 


< 


< UJ 




U- 


■a. 








U. Ui 








■>»■ 




o Q. or 


*-* 






?: 


a 




> 


X 


o Ul X c-1 


-J 




m Ck 




OD 




U UJ 


V- 




t- 








3 J 








1- 




(- 3 X 


X 


»— 




►- a. (fl 






y. 


UJ o a. •<» •« 


tv 


o 


•* < 


>- 




Ul 


■« u. 


Ul 


y: 


lO 








IE t-* 








eo 






UJ 


«n 




a: 3 -5 


K- 




■« 




-10 2 0. 


•-H 


I— 


►- 


u. 


oc 


_l 




ts 


2 










U. 












•«:■<» 




3 




Ul 


X 






« 


1— t— 


1- 




UJ 


*~* 


■a. 


<P 


a Ul 




♦-f 


2 


2 






(O 








m 




^ ^ i/j 


Q 


-5 




CO 1- 1— o 


CO 


« 


CO 


^ tn i- Oi 


_l UJ 


In- > O 


UI 


< 


O 2 


« 


_I 


UJ 


Z O 






3 >- 








o 


►- 


(-( t-l UJ 


■,7 


o 




■? Ul Oi 


»-l 


Ul 


o 


Ul 


O U! Ul 3 


3 


tfj 


u. o 


a 


_i 


z 


O M 


a 


2 


a 


O Q. 






t- •« 








■-> 


J. 


_J _i >- 


•< 


•4 




•-• 10 OJ 


-i 


>- 


2 


> 


2 ar IT CO 


X 


3 O I 


X 


(J Ul 


_• _I z 


3 


_i 


a _i 






•« _l 








•M 


i-i 


•« ■«. a^ 


M 


•« 




•« »« •« 


•« 


•« 


•« 


«« 


•^ M. Mb Vtk 


•* 


•« 


•>. M 


•^ 


»k 


•« 


»« •» 


■^ 


•* 


•« 


_i -• 






t- Q- 










IK 










































-• u. 






>/3 OJ 










a 










































2 U. 






K- 










a 










































o o 






z. o 










te 










































^ >t 






Ul 










►- 










































_l_l 






a «« 










►-» 


























•-• 
















aD in 






_» 










X 










-i 
















a 
















— « — « 




vt 


• >- 










iij 










CO 










--• 






- oc 
















1/1 ^ 




» 


u. 










a 










-> 










at or 






• t-a 














t- 1- 






UJ •-» 










* 










n 










»— ^ 






1 a. 


»- 














2 2 




UJ 


X o 










or 






U. 




Ul e 










a CM 






s ►-* 


a. 






(S 








»-« K-4 




_l 


1- o 










z 


•J 




3 




_1 u. « 










-< ♦ 




.-H 


XI •. 


>-i 






ac 








-a -a 




a 


X 










>-^ 


lO 




!D 


e> 


>-• O 5) 


U. 






»- 


»- « u. 




i: 


•a •-. 


« 


u. 




t- •. 


1- 






a: oc 




X 


<o 










t- 


X 




CJ 


»j 


u. tr ^ 


73 






»-• 


CO « r> 






t— *-4 


^ 


3 




CO r\J 


co 






■>! -« 




« 


Ul o 










►-■ 


V UJ 




UJ 


i 


Ci _| ^ 


T 


V 




X 


1— (\j aj •-• 


^-« 


CJ 


a a 


--« 


tt> 




f- *-• 


»- 






X X 




X 


<o ►- 










a 


-♦ It 




tt 


it 


» n *t 


_» 


*-• 




UJ 


_i M -I a 


a: 


a. 


« ^-' 


»-<i 


_» 




_i « 


_i 




(^ o o 




UJ 


or 






















































IT. 


UJ 


UJ Ul 








3 


_J 


»- V- 




_l »- 


»- 






a 






















at 








_i 


_»t- 


IS 


*4 


r- =J 


-Jtt 2 


K- 


o 


2 


a: 2 






2 






















2 


t- 3. 


o o 


Ill 


»- 


a. »j 


M 


»< 


M 


n 


■< 


J£ <-f 


►-• 


a. 


►-« 


<o Ul 






•-« 






















_l 


>-• sr 


Q- a: 


(A 


*-i 


x •-• 


n 


n 


n 


z 


(J 


Z -I tt 


X 


o 


(Z 


iT X CO 


t- Ul 


»- O 


>• > CJ 


-J 


a 


o > 


> 


Ql 




Q. 


UI 


^. 


X -to a 


•« 


►- 


<I 19 


ea 


«-* 


(J GO 


I 


-1 a. a. 


Ui o> 


a. 


»-* _1 !-• 


to 


z 


»- o a: o o UJ 


CO o 


O <3 O 


-J 




IT X 


z 


3 


UJ m 


3C 3C 


a. 


a 


■X Ui 


at 


a 


Q. 


-» 


a 


a QQ a 


a 


a 


a 


> a a OD 


»- 


CD 


a 


CO 


03 X X O 


4 


< 


-«■ X 


X 


CJ 




CO CJ 


m 


a 


a a 


a o 


=r 




UJ a 






















































a 




V> UJ 












•• 










































«• 




M i: 












»- 










•• 






















a* 






■a 




o- 




I -a 












a. 










(- 






















8- 






u. 




=» 




f- i 












■a 




•• 






CO 








CM 














»-4 






3 


e« aa 



z 


>- 


o 


•< 

X 


h- 


i 


O 


CC 


O) 


9 


c 


a 




hO 


CO 


ca 


3 


X 




o 


tf) 


(E 


0) 








a 


X 


E 




(S 




N 


-^ 


m 


a- 




Ul 


o 




^^ 


X 


■ 


■« 


< 


X 

111 



=1 

G 
IS 



IS i 
Lj IS 



rvi 

IS 



^ e»i 

IS IS 
S IS 
GJ IS> 

IS 'S 



rvi 
in 

S' 
IS 

& 

IS 



ni cs nj -o 
-o o ^ -» 

c& <si G c& 

'S CS Si S 

:s IS IS ca 

S K. S Si 



6. -< r^ « 

ca s s a 
OS s s e>i 
s s ea 's 

IS S S9 S 
S 'S <9 S 



53 



K>.D!S f\it~.r^'SSisiSiS-or-^ 

51SS) ■— issinissisiasiss 



s 

<s 



S Q» IP 

in s 9 
^- p- fi 

S <M -< 

IS m s 

(S S 19 



S IS 



e>i7<oi3.o.07iaa'rvioisru3 ■o:i'isf\t=r-i>r\i«o 

5: .■aoa>-«— «(\iro=»m c-or»-h-r^r-is»-«"-»-<"-<i>imo 
sasGa>sisisi!>siis (sscs<s»->-h»<..<»<.-.»-«.< 

ssssssisssissssiissiiaiscssssiss 

SSISOiaSSlSGi>SIS(SSISISSSSS(9S(SC£ 

ssissisisstais s:sis.<9SS&<ssGiesscss 



IS r\i -s 

« =» 5» 

•-• a-^ «-• 

IS s ea 
IS ca o 

G> O C9 



lmm^m'4>^-co<r-C3i<-•<\l^04m•cl^co(^s:-<rvJtOla^ln•o^-coc^s<-•(xl^^9ln<or^Q> 



s 9 >o 9 A 

in in in »^ i«- 

w4 v-f «-« a-a a-« 

S S S IS S 

CB s s s ca 

ca Cd S CS S 

» El a-««\l 1*1 

m a- =a sr a 



Display File Handler A-27 



a.' U.. 



_j •-• o 

1-1 o »: 
J. o 

S i »- . 

>- a -i <f> 

•« U-- >-i 3 o 

_i a: i_ o a 

a -a o oj 

lO o i_> >- ^ 

i-» t- o u.' ■< 

o _i 21 a. CO 

I/; »-• o CO 

U- 2 CO _l 1— UJ 

a o z> V 

n o _i _i 

uj »- M _j _i q: 

_j ■« 3- o o o 

cc cj Lij m 'X. a: 

-« o or cj cj ar 

I— _» a CO OT uj 



< 

cn 

CO 

UJ 



o 

CL 



O 

a 



o 



« 


c 


a 


(M 


rr 


£ 


O 


'SI a 


-<« 


«. 


■s- iij 


X 


-^ 


■^ 0.- — 


lU 


Q 


o rvj -• \ 


\ 




N) 


M 


c; 


(=1 O O !-• 


»-l 


a 


ar a: oc »j 


O 


o 


O O O CO 


CO 


ic 


« i: I <« 


•« 



-I 


~ u. 


•« 


■? 




OD 


IT rj 


ta 


UJ .. 




< 


t-ro 


CO 


>■ CO 




>- 


a u 


T 


lU CO 




O 


i-« CO 


^ 


• X 




% 










fV 




t\i ni 


^ =T 


K1 


--• 




rvj f\i 


SI ■rt 


3 


K> 




•-* w-t 


«-t *-• 


S 


S 










ts. 










s 













■«l 










^ V 










^ ^ 




£ U.' 








X 










1-4 o 










^-4 « 




i-l UJ 








UJ 










— -U 










— o 




u. .r 








or 










u. o 










U. K 




U. 1- 








o 










rj V. 










o ^ 




O V 






•-1 


u. 










5t 










X 




Yf 






9 












_l 










_l 




-J 






in 


Ui 










03 •-• 










IE ►-" 




m i-i 








_l 


t- 






UJ 


— • ►-« 


t- 






U.I 


— • ►-» 


►- UJ 


-• i-i 






UJ 


•-• 


^ 






i 


a. u 


^ 






i 


a o 


^ 2. 


rx cj 




1— 


C9 


u. 


►-• 


«. 


s;' 


■< 


•«t lO 


—4 


» 


"V 


■* 


•« CO 


•-■ S S -4 


■< CO 




UJ 


•t 




a 


US 


Ci 


z. 


X « 


o 


I!> 


ts 


^ 


X ■< 


O PS IS ^ 


X ■« 




tr 


a. 


>- 

<4 


Q. 


•-t 


.r 


C-. 


wo . 


a. 


— • 


rO 


o 


rvi LJ . 


0.-^0 


fO CJ . 




o 


^ 


-1 






























a 


Q. 


•• 




























»• 


CO 


UJ 




























o 


»-• 


-J 




























ti 


o 


n 








•• 










•• 




MS 






•• 




u. 








•-• 










CM 




1*1 






:3 


•« w^ 


~.o 








o 










O 




o 






— 
































r- 












in 










1^ 




r\i 


■c 




r- 












•a 










•-• 




rvj in 




9 












•— • 










«-t 




«-• 


s 




>- 
































< 
































». 
































8 
































<C 

































ui r*- ea *5i s k ri 
s ■-^ fs Ki c\i ^ da 



IM 






Wrl IS 


w w <Si 


IS. 


S 












Si 












!S 












« 


% 










»\J 


rvi 


r\i (S 


^ ru ^ 


■n in in 


.i^ 


m 


m 


CS E 


^ f»» ^ 


tSS =^ iS 














^w 


nj 


fvi 


E! -< 


ea .^ s 


«-l «-t «-4 


e>i 


cs 


a 


s s 








s 


SI 


s s 








s 


s- 


S (S 









6. 



tx. 



IS in 



ca-^ininoi'-'-^ci Om •-•Kim ej»-«»^c»^^«*^ins^4«"i*-«5i 

aStifO^fO ^caSKlSrO :aS.SKlSr*» (O 

•-•s-s*^ii--i -"irss:-^^*-* ^-•isS'^r.s.w *-• 



s 'O'scxjsjr^fxi ^r^rxiin 

K s*^*-i-^-^fvj fxjojroro 

r\j (VimrvirurMfM rvirxjcMCM 

S SSCSS'SS ISISS.S 



sc\J9<osf\J9r^isr\i^^srvi^r^srV9<osf\i^r«fv 
9994'ininknin'0.o-o-or^r>-r>-r~c3(s s»s-<"-i-<»<(m 
r\if\jcM>\ini(\l<\truc\i(\in;i\ini(virMrMKirOior'imroroi«ii'i 

sss'SiSusisi&SiiccsiisiS saassssscossss 
(S<iss:&c;<G:5)s;i:assse>.c:sscie£G]eass:sscB 

C^IS&&c:»CAaiS<d»SC!9Stca51IS<OS>&'SS2^GISSS 



9 vn -o 1^ CO (^ 


BB w 


r\i 


-I 


sr =1 .» ~i a =1 


in in 


in 


a 

z 



i'i«in-«ir-aic»-OE»<ru 
inintnirinmin<ONO-o 



M ^ in -o r* «o o- 
•o .<> *o vO ^c ^o .4) 



cs -• (M M sr in >o 



1^ 



A-28 Display File Handler 



X a. 

■^m-«3<S.^3-« 33 » SI'S. 

II H II II II H II II II n II 

>■ •« in — * X V I— 

_J»^>-q: f-i-ijn.Q.«>ii-j» 

•-•I— xo -»'«aj'«»-«»^o</j 
u.ir-<Ji-»t-i-->xa>a.»-< 
o«-«^«>ciOT!ni«t;>i3w»_ir: 



o 
a: a. QL. or cr 

srviQ9'0-03&7S9r-is« 



n 



11 n M n 



u 

3f 



-t t- u> a:<3u<o xcrz 
•-•-jt-iMMOajOTM'oiraw 



a. cc 

si-«ta'ss>ru(S'«« S4«ms 
i#icass9siaeB'Ci sm«m3 





ra 






B 


X >- ir u. V 




m 


a> o> >- s ui b. _i UJ 


o 


lal 


l-OZ^MOl-V -ilCCOOC'QO 


2 


O 


■"ZQ.>-«wOIt--<>-_n>-2 z 


UJ 


«I 


i->_iz:3:a.uJ>-*>->tf>xot<«oo 


• 


a. 





tn 

UJ 
L9 



(9 

< 
a. 



3 





•9 
















a. 
















t- 
















J£ 












(E 




UJ o 












O P« 




X _l 


o 










»- CE 




1- _» 


r*> 










>-• O 




o 


s- 










z tc 




o u. 


<s 










o oc 




z. 


ir> 










X UJ 




■"I o 


^ 














t- 


&i 










o o. 




t- 


■s 










t- :3 




«j a 


m 














UI o 


«_f 










Tf a: 




T> »- 












Z 2 




as o 


1— 










>— •-« »-8 




O UJ 


•■a 










3t _» _1 




>• 












t-« Ota VM 




13 


«- 










K 




Z -fl 


z 










a. 




t-4 


k-f 










e 




3£ UJ 


o 










^ 




o <o 


a. 










Z- 




•a o 












•-I 


ni 


tt -"i 


»— 










>- 


o 


t- o 


UJ 

at 












UJ 


UI o 












o 


-J 


X t- 


•» 










« 


X 


^— 












»- 


s 


UJ 


X 










B-a 


< 


CO z 


o 










X 


X 


UJ e-4 


g: 










Ui » 


UJ 


O 


z 










o v-a 


UJ 


UJ a: 


UI 










_J »- 


_J 


_j 


a. 


s 


-^ 


•u t^ _j o: 


t- 


a. z 




M 


M 


»« 


»« 


•« ^ 


1-9 


X o 


•— 


^ 


ei 


n 


m 


O 2 -1 


►— 


■< ft 


X 


(9 


▼^ 


a. 


u 


X _JO. 





X »— 


19 


a. 


q; CO 


a. 


o o tD 




UJ UI 


»-* 














_J 


_S 














U) a 












09 




^H S. 


UJ 










(- 




I o 


X 










DC 




1- u 


►— 










-a 



1^ 



9 



IS 



to 

SI 



Q9sms>sis<oc9e^st^-o^<s 

(SC\IISSSIS>S<\ISK)SSCd& 
9S>IS>0>-<S&SKIt^St9e9S> 



H n n » 



H SI 



B9 SI 



et II 



n tt 

iC > UI 

•-• > Ot <M »- 1*1 »— 

x(\iujqlC9'4ujki<i>— uJu.a:>-> 

»-l-Zy. 2QZ»-_fU!2 3U_! 

zz>->"ooa-'-«2jjQc*-«oozaL 
m«-i_ic>_i_i_i>-'q:o_i_jm_i 



a (o 

vx UJ 

o 



o -o 

a: 

a 

o 
-;» u. 

inuj 



eg S 

S 19 

C9 Ci 



9 



■a -• 

Si S. 



CD 



B 






Si 



X 

o 



IB 



to o- 



oc a a oc ol 

f\imss<<Mr^si9iss<si7SfS 
r^=»«aB)-Hit~-(S»<\i<Spo<sis:scs 

UJ <M-<S.OrOS'^!M(\ISinSSrVI 

_i eaesfMr^-issTaisfMStoeiirso 
^3] ssifS'MCSss'Sssi^p:. ss 

U •< ISS5'&eSSl9ISC£.CS<^»-<«-4S 



n n 



ti n 



n n n « I) 



a o 

Z CD 



X >- 

UJ Ol 



X >- >- 2 »- IS _l 

i-sio co>- --o_juja:as 
t-i»-x xcoc9»-i£«a2«»-« 

IMXZ-<hO-4f-4«OZ_IX>-tI»- 

oui>-<xoxz s: t-t ID a -i u a 





CO > — • 


•• 


■3 •< X 


o 


UJ 


rm ill 


>- >- z 


isnt t- 


a a •« 


S ro o 


O O X 


SI ts UJ 


X X • 


!si e> ►- 


UJ UJ u 


Si S UJ 


X X ■« 


o 


X 




-I «J 1- 


• CO 


■>«.•-•>• 


CO cc 


3X 11 


u o 


»- -a •• 


4 oc 


a z a. 


oc 


i-« >- _i 


• UI 


>■ o • 



(M 



_i •^(\J^^9ln<af^«o(^s>'Ml\ll 



s, .M ,«, r^ 


Q 


S CB <9 03 


19 


■■7< ivii lev or* 


agv 


v«> <ur *.w ^jm 




SI IS >S S) 


IS 


O S Ol s 


B- 


<S S Si S 


w-« 




Q 5r 




s s 




cs ea 




IS IS 




<s s. 




IS SI 



CL 

X 



Display File Handler A-29 



n "-5 

o 



o 



o 



ac 

Ui 

<o >- o 

-I o a: 

at a. ■« u z. u. o 

a CO a: V o i»- z 

O I-* t- (E . Q < 

U- »- Q cc u> q: uj 

y M >- o ■« Ui I- 

Hi or _i z »j C3 
<» UJ a. »— 1-^ Lij 

<oafoio>-i_) i-jr » 

UlZ^>-<-«Z U.I-IO 



o 



I- in 

UJ ^ 
•- 1/1 



-r 
Ui ^ 

oo I- 



-3 

a 



CD 



IS 



_J u. ■« 
•-• 3 ■« 

X la. in K 

isi a !-« tj 

^ ^ ^ OL 






in 



rf •« o s 

n 1 OLirt 



_l • u. 

I- UJ <r 
a. a. I- 

li Q. 

a: o X. 
ac »- o 
ui t/3 a: 
»- u. 
z >- 
►-« < < 

_i ►- 
►- a ■< 
•< oj o 

►-♦ 

O D X 

UJ t— 

or I n 
UJ »- « 
»- t-> 

Z -3 UJ 
UJ _J 



JL -J 

•-• Q >- ^^ 

»- Z < O- -- 

z) •« _i CO a 

Ola ^^ «. -< 

l£ CO 9 tL. QC 

Ui •-• « 3 > 



UJ > 

o «-• >- _i 
-<: •— f— U- •-« 

Uj »-H »— • •-H U. 

a: c« cc CO tj 

uJ o y. 

■K u. a </> UJ ^ 

»A. Z) »— »-• 

i_> »-■ UJ ^ j: 

_l O VC •-»»-« uJ 

o «i ». or. 

UJ i ►- o 

I > I— UJ ►- 

►-« O OJ <« CO 



oJ >■ 



a CO rr o _i 
oj o a 

>- u. u. cr- -«: i 

u. _> »-i o 

Q •-« u. x: (_) 

-I O V. t-* UJ -^ 

c3 < i !x o: I. 
UJ t o o 

I > I- H- UI £r 

— • o UJ to or u_ 
xxt— c/:«r> >->-»— CO «r- o 

UJ •-* oz ►-* z >~ *— 

>ixco» i-couJKjrco »nujco«-« 

-«UJUjoo-D_iruiuiOOi.-xujx 
co2i!ii,2:cr)««i— zzaz-c«i— oruj 









xl 










■cc 


c 








UJ 


z 








r 


UJ 






a 


H 




»- 




o 


o 


uJ 


<J 






jT 


_» 


»-• 


«-> 


UJ 


>- 


u. 


i 


rv 


■j> 


-I 




l-» 


S 




-1 


>- 


o 


ir> 


«» 


•>* 


■« 


CL 


« 




►-• 


_i 




■s 


^ 


l- 


a 


I— 


s 


•< 


•-i 


CO 


UJ 


ir> 


» 


z 


•-* 


CO 


•^ 


o 


f-4 


o 



• — • ir 
j< □: > 
lO •. rvi 
3 X X ■»- — • 
Z »- Q U. tE 
•-• Z «. 3 •. 



X IX 

CO •. 

3 >- ■♦• 

2 O ^ 

►H « n. 



Z_JO ■'<CZ5X4A«^3c:e-««-«fj3>^V»«^X--«COO 

ow QTH-o— •ae««n:(-Of\iQci»a:'>-»(L 



»- I- St 5«: z 

z»— occj z»->-« o 

•~ii-icn< «jii-i>- rx. 

ot:xzoiQ:z>t t-a.uicoo 

a.iij>-ai-co3iu^zz»-z 

a a • « *~3 • » » CJ Q3 Q^ s 






Ui >- < 

_» ■« o 
a -I CL 
X a. z3 
o CO 
cj •-• o 

o I- 

(J X o 
■4 O UJ 
IX (£ CO 
»- U. 13 



A) 



a. 

z 



or 
o 

UJ 



■ CR w 



> O Q 

•-• z ts a u H- 

>>2>— »C3cOin>.>.iri_it3(/3>.>oj q_ •-•sszoouj 
oor30.ui»-<Mi3O3auj>-iaoH- osjiscaijiac 

z.xioasztnjDxscoxizcD'Eia: >- ti.'ji(n_i • #0 



X 

o 



a ~ 

CO uJ 

>-• _J 

Q M ~ ~ 

U. X >- 

~ ~ ~ :3 o o 



X >- 



IS 

s 
<s 

IS 



s 

IS 

OS 

IS 



-s 

■s 

IS 
IS 



-o rvi 
-o in 

r^ >%. 

-I IS 



O IS IS IS :3 

CS O =T =» fVl 

IS s s> r>- cs 

IS K) <S 1^ S 

(M =r s r- s 

IS S S — • IS 



<s: <o 

Sl -« 
S IS 

IS n^ 

fXi K 

iS IS 



IS 

<s 



5i »n ^ 6» 

Kl 1^ <S S 

Kj -* <B as 

ru s SI s 

IS S IS IS 



:j^SIStS.SS'^ISIS.:S'S:S*IS^ 
=^ r=^ r^ IS ^ 1^— f^ »^ r^ 1^— ^ ^ r^ ■-• •w t\i 

SvO osu>rvirus.o-os. miMsrvis 

eiQ-^-^(S(SS ■3(S-^--<ISCiEj«SCi 



IS & S &^ S) CJ cs 

IS &I IS (S Si St IS 

S^ iri if t S ^ e; 7 

3 S IS K> O S -O 

»-• IS s. -• s s r^ 

— • es s -< s. s -» 



•09<i>-0>M<OCM9S9<OCS 

<a»-»»-<fM=»^min-o-o -ot~- 
sissc9ea(assis(sessi 
sss(9<sseassi9ss 

SCSISSCSSlSCSGiSISS 



3 •o>\l•oSlnl>oe\i^>r\l^lE!m•ot\^^ 
^^r-ss-^-^-H(\jnjKiKi^5»c»4nm 

SSI— •'^'^•'-••^'H.^W-.M^^^^ 

ISSISISSTaSlSlS'SElEl^ejISE^ 
ISSSSISSSSOUISSISSllS.'SCS 
CSSIISSISSSiCJSS S&iSIS.SS 



« IS ru a « s CM 
in <o -o <o -o r^ r- 

V4 W-t «-• «-4 V4 «^ •IF^ 

S> IS IS iS S S 3) 
S SI &> Si IS IS IS 
IS Q S S IS S S 



94n-or~ix>o-S'4'\it09in-or^coc>ia'-irviKi3m-or-ioo-c>i— •ruKi^in<or<-<x>0'is^r\ir<i^in<ot^ 
M^^^^Mrvi'MfM(Mrv>fMr\)iMf\injpnKir«iKiror'>r')rOr^K>^ ^ a-^j- =J ^=j ^ a ^intnininintninin 



ASO Display File Handler 



u 



« J1 :s r^ X. -ci 'J t^ ri « .'* -i: 
« -^ ro ■^ 3- V ^ -_ J ■» ^ t'l. 



« 3; 






II 



nun 



II II 



I uJ 



II II II 

^ -O tU X > I- 

^- in u5 i X r u- X 
^jr->-;i:i- ►-a<xcou.>- 
::>>-ii— xo< ■«.-*< io to 

« Q >-« I. in «5 fO CD 13 i«- _i 3 






« SI (S s S s: 

« fU 'i5 -C S (M 

« in S Sr IM 9 

* rO ^ G3 r^ '^ 

■ft r^ 4) s« s r^ 

<t »-•--• K- £* -^ 



n II u 11 II 



a: a: a 

=r c» r- as s r\i 

IS til r^ -o i o 

<i> =3 r~ •-> <si ■— 

(S rO •-• ^ iSr 'S» 

5> S aJ S tS :S' 

S <5J K> "^ T IS> 

H 19 E3 



Ul 



_| lU — 1 I- f- 

i-Eo iir>< o-ox a 

ar«ro-<»— »- zi-x «» 

>-^?i-z«o v2'-<s>rt->- 

v*00»-<*-tO (»i-iX. o</>o 





UJ 




i 




»- 




» 




>- 




a 




a: 









10 




-V 


•^ 




> 


rsi 


in 


•-< 




u 


Ul 


CO 


t» 


•< 



o 



CE 



DC 



m 


«« 


•• 


u 


o- 


<o 


=» 


3: 






2. 
1 

CO 



X 






a. 

X. 

X 



(\«=»sinmr*>r-inis»^m 

IMin^'IS C9(\I«->G'9<mC9 

v^ C3 «^ *^ "r^ «-* «~* «^ S "^ *^^ 






sKiruKincsmsssiamm 

^5 1^ ^U 9 (2^ ^7 ^' cs ^f ^7 ^i Si 4*4 S^ 

^ «-i «-• 3 ^^ S "-• S C9 S •-• ^-* <^* fS 

•S (9 

IS (9 



•^'^iMmr\ir\im<M(Mr\irMmni 

siseasssesscBcgsss 

lassKsssseatsBss 

It) o- c 

in in 



at 




fM S 


« C£ -♦ S 


■4 




(9 S 


« K» » «n 


>— 




S S 


« IS G> ru 


CO 




s fa 


« R) K> IS 




ni 


Si 


m m m a 




a 


UJ 


St X 




in 


►- 


"C «o 







>-t »- 


tr ar z o 


j: 


UJ 


_l •-< 


»- »- j: 


Hi 


U) 


Q. ■< 


M z a >-• 




•a 
a 

in 


_J 5 


»» •-I _• i: 


UJ 


«« 






>■ 


o- 






111 


w 






9 


ar 








«-• 




0: 






IS s 


A ^ (S >s 




r- 


CU Gl 


IS <0 S IS 




i^ 


s r»> 


s -< -0 ^ 




9 


s sj 


s ca ni 5. 




>- 


•^ s 


IS IS fa M 




< 


•^ IS 


K. IS 5. -• 




T 








> 


n B 


N ei II 




<o 


it 


> 




«-■ 


> a 


<V1 »- 






-a 


UJ pn < 




-a 


2 


? 1- _J 




SI 


a 


>-• X Z UJ 




• 


_I _1 _l >-< QC 




to 






% 


s 






Si 


X 







Giin-cics^is &.^r<»9nits 
•s s w s ■!. 1 
s ^ ea IS s Ki 

(\i -< s (5 £1 r^ 

<9 *-• ^ d Cy ■'^ 

u a M n n 
>- u. 

»} •- IS u. 

3 z to _i o a 
^ n JO ■« 5£ 03 
>-< o 2. I- _i -:» 
n Q. ul n aj o 



3- IS »~ o s s 

f^ S Q B^ r*- Ci 

S ^ ® •-• IS *-• 

fSi ro s s es cs 

ca (~- K ■s IS Si 

Si *-• Oi s <&> e"> 

6} ^ G3 



Z S- Ul U- CE 
O Ul 2 30 

u ot »-< >- m z 
»- o _J o »- t-l 



U) 
(9 



in CO 
«- ul 

t9 



to ^ 

a 
o 

S QC 

o 



ro _l 

03 



IM IX! 



a. o 

X CD 

X >- 

Ul CO 



<s --• 
& S. 
■% 7, — -t 

Ul -t 

<n >• IV 

O UJ 

IS IM UJ >- >- Z 

(s =» I- ac a ■« 
s IM o 00 a: 
(s SI UJ X i: • 

SSI- Ul UJ u 

CS (S Ul 2: Z al 

O i 

_l O I- 

• vi «!►-•:» 
x>->-zi-si ■" «oQ:3in 

!Scoco>--<a _iui(rx(\iuia. tn o i-^.. 
>-xxco»-!st -az-«»-»-Zi < or qcZq. 
— --— - X»-»I2Z»-»*0 It t-f>- -1 

Q_ju>-'>-i_JQ • ui ■^00 



ssr^isss s^sssiinis 

'S-oS'<iMS in^!SS^iss 

rMr-<sea(MS roisesisrvi<s<^' 

SSIS^SS »-»(B-^C:S.!S— • 



H EI H Q n u 



Z ■«<>-• Z _l 
M Z I X >-l CD 



Bt 17 ^ E9 B9 Si H 



Display File Handler A-31 



Appendix B 

System Macro Library 



This appendix contains the listing of the system macro library (SYS- 
MAC.SML) for Version 5 of RT-11. This library is stored on the system 
device. It is used by MACRO when expanding the programmed requests 
and calling the subroutines that are described in Chapter 2. 

MCALL ..MODULE 

MODULE SYSMAC »RELEASE = Y05 fUERSION=lB »COMMENT = <Syste(ti macro 1 i b ra ry > tL I B = YES 

COPYRIGHT (c) 198^ BY 
DIGITAL EQUIPMENT CORPORATION t MAYNARD > MASS. 
ALL RIGHTS RESERVED 

THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED 
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE 
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER 
COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY 
OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY 
TRANSFERRED. 

THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE 
AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT 
CORPORATION. 

DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS 
SOFTWARE ON EQUIPMENT THAT IS NOT SUPPLIED BY DIGITAL. 



+ + 



+ + 



RESERVED SYMBOL NAMES 



.VI and ... V 5 are "global" values defined in w a c r o s 

.VI -- controls .MCallinS of ...CM* and support of VI t V2 and 

V 3 versions of the expansions. 
. V5 -- controls feneration of .Audit information. 



.V^ 



re reserved for more local and Slobal values 



.V2t ...V3» and ...V4 are in use currently (Y05.0B) as 

local symbols (reusable in each macro definition). 



RESERVED MACRO NAMES 



. . VI . . 
. .VZ. . 
.MACS 
. . .CM* 



Error Messages 
?SYSMAC-W-Inval id argument, use *0 . not 
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General messaSe -- Macro arsuwents of "0" are almost always 
errors* (Which specify an address of Ot not a value of 0.) 

?SYSMAC-E-Odd or invalid vector specified 

.DRBEG &: .DRUTB -- the 2 lower bits of the vector address must 
be 0. 

?SYSMAC-E-Inval id control value - control 

.DRBOT -- an invalid controller type was specified. See definition 
of .DRBOT for valid type codes. 

?SYSMAC-E-Inval id s i d e s value - sides 

.DRBOT -- an invalid number of sides was specifiedt use 1 or 2. 
?SYSMAC-E-Primary boot too larSe 

.DREND -- the primary boot code overflowed the area available to it. 

7SYSMAC-E-U A L Must not be Ot VALi 

.DRSET -- the second arsument to the macro must not be 0» if it 
is* the rest of the options in the table are ignored. 

?SYSMAC-E-Inval id parameter x! 

.DRSET -- the last argument must be blanK or one (or more) of 
the following: NO.NUMtOCT 

?SYSMAC-F-In valid A D Rt expecting «...» found - ADR i 

.ADDR -- the first parameter must be an immediate value i 
like «F00. 

?SYSMAC-F-Inval id REG expecting - Rx or @SP - found REG ? 

.ADDR -- The second parameter must be either a simple 
register reference or @SP. 



. , U 1 . . 

.MCALL the support routines and set the version to 1 



.MACRO . .VI. . 

.MCALL . . .CMO ». , .CMl ». . .CM2 ,. . .CM3 .. . .CM^l ,. . .CM5 .. . .CMS ». . .CM7 

. . .Ml = l 

.ENDM 

i+ + 

! . .U2. . 

i 

! .MCall the support routines and set the version to 2 



.MACRO . ,M2. . 

.MCALL . . .CMO ». . .CMl t. . .CM2 ,. . .CM3 ». . .CMa ,. . .CM5 ,. . .CMC t. . .CM7 

...VI =2. 

.ENDM 

;++ 

i .MACS 
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! iMCall the support routines and set the version to [>=]3 
! -- 

.MACRO .MACS 

.MCALL . . .CMO t. . .CMl .. . .CM2 ». . .CM3 ,, . .CMH ,, , .CM5 .. . .CMS ,, . .CM7 

. . .yi=3. 

.ENDM 

;++ 

5 ...CMO 

! Moue a word to the stack. If arsuwent blanK or «0 

! Put a on the stack. If second arSument present* 

5 Generate an EMT with that value 
5 — 

.MACRO . . .CMO STARG»INS 
.IF B <STARG> 

CLR -(SP) 
.IFF 
.IF IDN <STARG>»#0 

CLR -(SP) 
. IFF 
.IIF IDN <STARG> <0> . ERROR !?SYSMAC-W- In val i d arSument* use #0 , not J 

MOV STARG.-(SP) 
.ENDC 
.ENDC 

.IIF NB <INS> > EMT "0<INS> 

.ENDM 

5++ 

! ...CMl 

5 

; Setup RO to point to AREA i set the CHAN and IC (subcode) 

5 value in first word. This macro optimises number of 

! instructions to set up first word. 

5 IC is forced to decimal. 

5 — 

.MACRO ...CMl AREAtlC. CHAN. FLAG (ARGiINS.CSET.BB 
...CMS <AREA> 

. . .yz=o 

.IF B <FLAG> 

.IIF B <AREA>.. . .V2=l 

.IFF 

.IIF DIF <FLAG>.SET.. . .V2=l 

.ENDC 

.IF NE . . ,y2 

. IF IDN <CHAN> f<«0> 

CLRB @R0 
.IFF 

.IIF NB <CHAN>. MOVB CHAN .@R0 
.ENDC 
. IFF 
.IF B <CHAN> 

MOVB «IC'..1(R0) 
. IFF 

.NTYPE . . .V2»CHAN 
.IF EO . . .i,'2-'027 

MOy CHAN+<IC'.*'0400> >@R0 
.IFF 

MOV «IC'.*''0400.@R0 

MOVB CHAN»@R0 
.ENDC 
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,ENDC 

.ENDC 

.IIP IDN <CHAN> <0> .ERRORi?SYSMAC-W-Inualid argument, use «0 » not Oi 

...CMZ <ARG>»2tINStCSETtBB 

.ENDM 



;++ 



. . ,CM2 

Moue an arSument ualue to OFFSET(RO). 
Use a CLR_ if the value is *0. 
Offset is forced to decimal. 
BB is blank or B for byte operations 
If INS NB Generate an EMT 375 



.MACRO ...CMZ ARG tOFFSE>INS tCSET.BB 

. IF B <ARG> 

.IF NB <CSET> 

.IIF NE . . .Ml-3. » CLR'BB OFFSE'.(RO) 

.ENDC 

.IFF 

. IF IDN <ARG> »«0 

CLR'BB OFFSE'.(RO) 
. IFF 
.IIF IDN <ARG> <0> .ERRDR5?SYSMAC-W-Inyalid arsutnent* use *0 t not OJ 

MOM'BB ARGtOFFSE'. (RO) 
.ENDC 
.ENDC 

.IIF NB <INS>, EMT "0375 
.ENDM 

i+ + 

i ...CMS 

! 

i MoyeachannelandcodetoRO. 

; Follow this with an EMT 374. 

i This macro optimises the instructions used 

i to load RO. 



.MACRO . . .CM3 CHAN »IC 
.IF B <CHAN> 

MOU «IC*'OaOO»RO 
. IFF 

.NTYPE . . .U2 (CHAN 
.IF EQ . . .i.)2-''0Z7 

MOM CHAN+<IC**0400> >R0 



.IFF 

.ENDC 
.ENDC 

t ENDM 

i++ 



MOU *tIC»"OaOO tRO 
BISB CHANtRO 



EMT "0374 

. . .CM4 

Setup for a SDAT/RCVD EMT block 



.MACRO ...CM4 AREA »BUF tWCNT.CRTNdC (CODE 
.IIF IDN <CODE> (NOSET . . .CMl <AREA> »IC. »<CODE> 
.IIF DDIF <CODE> .NOSET . . .CMl <AREA> »IC.«0 ><CODE> 
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, . .CM2 <BUF>»4 
. . .CMZ <WCNT>»6 
. . ,CM2 <CRTN> t8»E 
.ENDM 



;++ 



! 
5 
I -- 



. . .CM5 

Move a (bvte) ualue to RO unless the src is 

blanK or RO. If so» then Generate nothins. 

BB is blanK for word operations or B for byte. 

If second argument present* Generate an EMT with 

thatcodeyalue. 



.MACRO . . .CM5 

.IF NB <SRC> 

.IIF DIF <SRC> 

.ENDC 

.IIF NB <INS>. 

.ENDM 



SRC.INSfBB 



RO: 



EMT 



MOy'BB SRC»RO 
*D<INS> 



!++ 

5 

5 

5 

5 

) 

! 

5 - - 



. . . CM6 

Move a code and channel to RO. This macro 
optimises the instructions needed to load RO. 
Do the first ...CM2 also. 
IC and CHAN are forced to deciwal. 



.MACRO ...CMB AREA. IC (CHAN (FLAG »ARG (INS. CSET»BB 

...CM5 <AREA> 

.IF B <FLAG> 

.IIF NB <AREA> . MOy 

.IFF 

.IIF ION <FLAG>.SET. 

.ENDC 

...CMZ <ARG>.2.INS>CSET .BB 

.ENDM 



«IC'.*'0400+CHAN'. ,@R0 

MOy »IC',*-^0400+CHAN'. .liRO 



;++ 

I 
5 
5 
i — 



. . .CM7 

Generate READ_/WRIT_ requests 



• MACRO ...CM7 AREA. CHAN. BUF .WCNT .BLK .CRTN.IC. CODE. yi 

.IF EQ . . .Vl-1 

...CMS <WCNT> 

...CMO <CRTN> 

...CMO <BUF> 

...CMO <CHAN>.<yi+AREA> 

.IFF 

. ..CMl < AREA >. I C.< CHAN >.< CODE > ,<BLK> 

. . .CM2 <BUF> ,a 

. . .CM2 <WCNT> .B 

. ..CMZ <CRTN>.B.E 

.ENDC 

.ENDM 



.MACRO .ABTIO 
.IF NDF . . .VI 
.MCALL .MACS 
.MACS 



CHAN 
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.ENDC 

...CM3 <CHAN>.11, 

.ENDM 

) 

; + 

; .ADDR ADR (REG. TYPE 

5 

; Used to compute an address in a position-independent wanneri 

5 

) 'ADR' is the address to compute with the « included. 

i 'REG' is the destination 

i 'REG ' way be s 

i R0--R5 jloadaddressintoRx 

5 @R0 -- @SP 5 load address into address pointed to 

; -(BP) jloadaddressintonewtopofstack 

5 

i 'TYPE' may be: 

i blank which acts like MOV «ADR .REG in a PIC manner. 

i 'ADD' which adds the address to the old contents of the register 

! 'PUSH' which pushes the old contents of the destination before loadinS 

5 

; .Addr #FDO.RO 5 load address of FOO in RO 

5 .Addr «FDD.RO.ADD ! ADD loads address of FOO+old RO in RO 

5 .Addr «FDO.ROtPUSH 5 Push RO on stack, then load address i 

> ; of FOO in RO 

5 

; .Addr «FDO.-(SP) i push address of FOO on stack 

; .Addr «FDO.-(SP) .PUSH ! same as .Addr #F00 »- (SP) 

! - 

.MACRO .ADDR ADR. REG. TYPE 

.NTYPE .,,V2.ADR 

. IIF NE . . ,M2-'-o27 .ERROR . . .^2 5 7SYSMAC-F- Inu al i d A D R. expecting «.... found - ADI 

.NTYPE ...U2.REG 

. IF EO . . .g2--'oi|B j 

.IF IDN <TYPE>.<ADD> 

ADD PC>-(SP) 
.IFF 

MOM PC.-(SP) 
.ENDC 

ADD ADR-. .@SP 
.MEXIT 
.ENDC 

. IF IDN <TYPE>.<PUSH> 
. IF GT . . .M2-5. ^ 

MOy REG.-(SP) ' 

.IFF 

JSR REG.SPC 

ADD ADR-. .REG 
.MEXIT 
.ENDC 
.ENDC 
.IF IDN <TYPE>.<ADD> 

ADD PC. REG 
. IFF 

MOV PC. REG 
.ENDC 

ADD ADR-. .REG 
.IRP X. < 0.1. 2. 3. 4. 5. 10. 11 .12. 13. 14. 15. 1B> 
. IIF EO , , ,g2--^o'x . . .V2 = 
.ENDR 

. IIF NE . . .V2 .ERROR i ?SYSMAC-F- In u a 1 i d R E G ex pectins - Rx. @Rx. or -(BP) - found R 
.ENDM 
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;++ 

i .Assume 
! 

i Used to provide assembly time yerification of assumptions. 

1 Generates a .Error if the expression 'A' does not bear 

i the relation 'rel' to the expression 'C'i for example: 

! 

i .ASSUME SYMBOL EO ZOO 

5 

; An optional 'message' can be substituted for the standard 

5 error messaSe 

! The optional error messaSe should start either with a '!' 

i or with a ualid assembly expression followed by '!' then the 

i message text. Example: 

! .Assume . LT 1 000 MESSAGE = < 1 000- . ! 1 o c at i on too hi3h> 
i — 

.MACRO .ASSUME A »REL »C (MESSAGE 

.IF REL <A>-<C> 

.IFF 

.IF B <MESSAGE> 

.error; "A REL C" is not true! 

.IFF 

.ERROR MESSAGE 

.ENDC 

.ENDC 

.ENDM .ASSUME 

!++ 

i .AUDIT 

i 

5 macro to Generate list of versions starting at abs 110 

i 

i UP to 26 names 

i First reference Generates a RadSO ualue for 110 of release 



Q »W »E »R >T »Y »U .1 .0 »P »A »S »D .F »G .H ,J ,K ,L ,2 ,)i tC .0 .B »N ,M 



.MACRO , 


.AUDIT 


Q »W »E»R 


.SAME 






.ASECT 






.IIP 


NOP 


. . .M5 


. = . , .M5 






.IP 


EO 


.-•^0110 




.GLOBL 


.AUDIT 


.LIST 








.MORD 


.AUDIT 


.NLIST 






.ENDC 






.IRP 


. . .02 <Q 


.W »E »R ,T 


.IF 


NB 


< . . .M2> 




.GLOBL 


' . . . 02 ' 


.LIST 








.WORD 


' . . .02' 


.NLIST 






.ENDC 






• ENDR 






. . .y5=. 






.LIST 








.WORD 


-1 


.NLIST 






.RESTORE 




• ENDM 


.AUDIT 





. . .05= "OIK 
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5++ 

i .BR 

1 

; Verify that a "drop-thru" actually worKs. Example; 

5 

i .BR Foo 

; . pa3e 

!Foo : 



.MACRO .BR TO 

. IF DF TO 

.IF NE TO-. 

.ERRDRiNOT AT LOCATION "TO"; 

.ENDC 

.ENDC 

.ENDM .BR 

.MACRO .CDFN AREA .ADDR »NUM .CODE 

.IF NDF . . .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

...CMS <AREA> .13 tO »<CODE> .<ADDR> 

...CM2 <NUM>.4.E 

.ENDM 

.MACRO .CHAIN 

MOy #^04000. RO 

EMT ^0374 
.ENDM 

.MACRO .CHCOP AREA. CHAN. OCHAN.JOBBLK .CODE 

.IF NDF . . .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

. ..CMl <AREA>.11 .< CHAN >.< CODE >,<OCHAN> 

.IF NB <JOBBLK> 

...CMZ <J0BBLK>.4.E 

.IFF 

...CMZ *0.4.E 

.ENDC 

.ENDM 

.MACRO .CLOSE CHAN 

. IF NDF . . .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

.IF EQ . . .Ml-1 

EMT ■'0<ieO + CHAN> 
.IFF 

. . .CM3 <CHAN> »B. 
.ENDC 
.ENDM 

.MACRO .CMKT AREA . ID .TIME = «0 .CODE 

.IF NDF . . .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

...CMS <AREA> .13 .0 .<CODE>.<ID> 

...CMZ <TIME>.4.E.C 

.ENDM 
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.MACRO .CNTXS AREA .ADDR »CODE 

.IF NDF . . .yi 

.MCALL .MACS 

.MACS 

,ENDC 

. . .CMS <AREA> 1 27.0 »<CODE> .<ADDR>.E 

.ENDM 

.MACRO .CRAk AREA. ADDR. CODE 

.IF NDF . . .VI 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA>.30>2.<C0DE> .<ADDR> >E 

.ENDM 



.MACRO .CRRG AREA .ADDR .CODE 

.IF NDF . . .yi 

.MCALL .MACS 

.MACS 

.ENDC 

. ..CMS < AREA >. 30. 0><CODE>.< ADDR >.E 

.ENDM 



.MACRO .CSIGE 

.IF NDF . . .VI 

.MCALL .MACS 

.MACS 

• ENDC 

.IF NB <LINBUF> 

...CMO <LINBUF> 

.NTYPE ...VZ.DEVSPC 

.IF EQ . . .g2-'027 

...CMO <DEVSPC'+1> 



DEVSPC .DEFEXT .CSTRNG .LINBUF 



.IFF 




. . .CMO 


<DEySPC> 




INC (SP) 


.ENDC 




.IFF 




. . .CMO 


<DEVSPC> 


.ENDC 




. . .CMO 


<DEFEXT> 


. . .CMO 


<CSTRNG>.34^ 


.ENDM 




.MACRO 


.CSISP OUT: 


.IF NDF 


. . .Ul 


.MCALL 


.MACS 


.MACS 




.ENDC 




.IF NB <LINBUF> 


. ..CMO 


<LINBUF> 


.NTYPE 


. . .V2.0UTSPC 


.IF EQ . 


, . .V2-"u27 


. . .CMO 


<DUTSPC'+1> 


.IFF 




. . .CMO 


<OUTSPC> 




INC <SP) 


.ENDC 




.IFF 




. . .CMO 


<OUTSPC> 


.ENDC 




. . .CMO 


<DEFEXT> 


. . .CMO 


<CSTRNG> .345 


.ENDM 





OUTSPC .DEFEXT .CSTRNG .LINBUF 
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.MACRO 


.CSTAT 


AREA>CHAN>ADDR>CODE 


.IF NDF 


. . .VI 




.MCALL 


.MACS 




.MACS 






.ENDC 






. ..CMl 


<AREA> 


»23i<CHAN> »<CODE>i<ADDR> »E 


.ENDM 






.MACRO 


.CTIMI 


TBK 




JSR 


R5>@$TIMIT 




.WORD 


TBK-, 




.WORD 


1 


.ENDM 






.MACRO 


.DATE 






MOV 


*~05000.R0 




EMT 


"0374 


.ENDM 







.MACRO .DELET AREA tCHAN >DBLK .SEONUM .CODE 

.IF NDF . . .VI 

.MCALL .MACS 

.MACS 

.ENDC 

.IF EO . . ,V1-1 

...CMS <CHAN>.<AREA> 

.IFF 

...CMS <AREA> 

. IF IDN <CHAN> .«0 

CLR @R0 
. IFF 

.IIF IDN <CHAN> <0> .ERROR ;?SYSMAC-W-In val i d arSuwent. use #0. not 05 
. . .V2 = 
.IF B <CODE> 
.IIF B <AREA>,. . .V2=l 
. IFF 

.IIF DIF <CODE>.SET». . .V2=l 
.ENDC 

.IF NE . . .V2 

.IIF NB <CHAN>. MOVB CHAN .@R0 
.IFF 
.IF B <CHAN> 

CLRB l(RO) 
.IFF 

.NTYPE . . .V2 ,CHAN 
. IF EO . . .V2-'027 

MOV CHAN»@RO 
. IFF 





CLR 


URO 




MOVB 


CHAN.gRO 


.ENDC 






.ENDC 






.ENDC 






.ENDC 






. . .CM2 


<DBLK>.2 




. . .CM2 


<SEQNUM> 


.a»E,c 


.ENDC 






.ENDM 






.MACRO 


.DEVIC 


AREAfADDI 


.IF NDF 


. . .VI 




.MCALL 


.MACS 




.MACS 






.ENDC 






.IF B LINK 
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. . .CMS <AREA> .12>0 t<CODE> .<ADDR> .E 

.IFF 

. . .CMB <AREA>,12»1 »< CODE> »< ADDR> »E 

.ENDC 

.ENDM 



.MACRO .DRAST 
.GLOBL *INPTR 
.IF B <ABT> 

RETURN 
.IFF 

BR 
.ENDC 
NAME'INT: : JSR 

.WORD 
.EIMDM 



NAMEtPRI »ABT 



ABT 

R5.@*INPTR 
'C<PRI#'040>8.*0340 



NAME >VEC fDSIZ »DSTS .VTBL 



.MACRO .DRBEG 

.ASECT 

.='052 

.GLOBL NAME'END .NAME'INT 

.WORD <NAME'END-NAME'STRT> 



.IF B 


<DSIZ> 






.WORD 


NAME'DSIZE 


.IFF 








.WORD 


DSIZ 


.ENDC 






.IF B 


<DSTS> 






.WORD 


NAME'STS 


.IFF 








.WORD 


DSTS 


.ENDC 








.WORD 


'0<ERL$G+< 



0<ERL$G+<MMG$T»Z>+<TIM$IT*fl>+<RTE$M#10>> 
.='017B 

.IIF DF NAME'$CSR. .WORD NAME'*CSR 
.PSECT NAME'DMR 
NAME'STRT: s 
.IF NB MTBL 
.GLOBL VTBL 

.WORD <VTBL-.>/Z.-l+"0100000 
.IFF 

.IF NB <yEC> 
.IIF NE yEC8:3. ,, ERROR VEC ;?BYSMAC-E-Odd or invalid Meotor specified; 

.WORD UEC5:"C3. 
.IFF 

.IF DF NAME'$UTB 
.GLOBL NAME'$MTB 

.WORD < NAME '*VTB-.>/2.-l + ' 0100000 
.IFF 

.IIF NE NAME'$yEC8:3. ». ERROR NAME '$VEC SSYSMAC-E-Odd or invalid vector 

jspeoified! 

.WORD NAME'*yEC8:'C3. 
.ENDC 
.ENDC 
.ENDC 

NAME'SYS 
NAME'LQE 
NAME'COE 
.ENDM 



.WORD NAME'INT-. >'0340 

.WORD 
.WORD 



;++ 

; .DRBOT 

i 

i CONTROL: 



is used to Generate the controller description bits 
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; in the boot blooK. The default value is correct for nearly 

i all RT supported devices. As Many options may be specified as 

; are supported by the boot codes 

5 

i <UBUS> Unibus device 

; <OBUS:> 0-Bus device 

i <CBUS> PC-Bus device 

i <UMSCP> Unibus MSCP device 

! <OMSCP> Q-Bus MSCP device 

; <CMSCP> PC-Bus MSCP device 

i 

i SIDES= is used to indicate the number of sides supported in 

i floppy disk drive. Malid values are 1 and 2. Hard media 

i sidedness is not coded. 

i 

i NOTE: the definition of a code does NOT imply any present 

! or future product committment. 

? — 

.MACRO .DRBOT NAME .ENTRY »READ »CONTROL = <UBUS tOBUS> .S IDES= 1 

.DREND NAME 
.IIP NDF TPS tTPS=-^01775B4 
.IIP NDF TPB.TPB=~01775GB 
LF="012 
CR=-015 
B$B00T='-01000 
B*DEUN="0471B 
B$DEMU=-04722 
B$READ='-04730 
.IF EO MMG$T 
B$DNAM=-^R'NAME 
. IFF 

B*DNAM='-R'NAME'X 
.ENDC 
.ASECT 
. = •^062 

.WORD NAME 'BOOT .NAME 'BEND-NAME 'BOOT »READ- NAME 'BOOT 
.PSECT NAME 'BOOT 
NAME'BODT: sNOP 

BR ENTRY-2. 

. .M2=-^0100 

IRP X <CONTROL> 

. .V3 = 

IIF IDN <X> <UBUS> ...y3=l. 

IIP IDN <X> <OBUS> ...y3=2. 

IIF IDN <X> <CBUS> ...V3=4. 

IIF IDN <X> <OMSCP> ...i.'3='010 

IIF IDN <X> <UMSCP> .,,U3='020 

IIF IDN <X> <CMSCP> ,,.y3='0a0 

IIF EO ...U3 .ERROR ;?SYSMAC-E- 1 n v al i d c on t ro I va 1 1 

5 cont ro 1 5 

. .M2=. . .y2! . . .i,'3 

ENDR 

=ENTRY-B. 

.BYTE "020.. . .V2,-'020,"0'C<20+. . .V2+20> 

IF EQ <SIDES-1> 
BR ENTRY 

IFF 

IF EQ <SIDES-2.> 



IFF 

ENDC 
ENDC 
ENDM 



BMI ENTRY 

.ERROR ;?SYSMAC-E-Inval id sides value - sides! 
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MACRO .DRDEF NAME .CODE .STAT .SIZE .CSR .VEC 

MCALL .DRAST..DRBEG . , DRBOT . . DREND . . DRFIN . . DRINS » . DRSET t . DRVTB ..FORK ..OELDF 

IIF NDF RTE$M RTE$M=0 

IIF NE RTE$M RTE$M=1 

IIF IMDF TIM*IT TIM$IT = 

IIF NE TIM$IT TIM*IT=1 

IIF NDF MMG$T MMG$T=0 

IIF NE MMG*T MMG$T=1 

IIF NDF ERL$G ERL$G=0 

IIF NE ERL$G ERL*G=1 

IIF NE TIM*IT.. MCALL . TIMIO . . CTIM I 

OELDF 
HDERR$=1 
EOF*= '•020000 
yARSZ$='-0400 
ABTI0$='-01000 
SPFUN$='-0Z000 
HNDLR$='-0/!1000 
SPECL$=-010000 
W0NLY$='- 020000 
RONLY$='OaOOOO 
FILST$='0100000 
NAME'DSIZ=SIZE 
NAME'$COD=CODE 
NAME 'STS = <CODE> !< STAT > 

IIF NDF NAME'$CSR. NAME '$CBR = CSR 

IIF NDF NAME'$UEC. NAME '$yEC = yEC 

GLOBL NAME'*CSR.NAME'$UEC 

ENDM 

++ 

.DREND 

FORCE is used to force the feneration of the Mector table 

assi^nind a ualue to FORCE causes the associated svsden 

bit yalue to "forced" on for purposes of Seneratins the table. 

F0RCE=1 will force feneration of the error loSSinS uector 
far instance. 

MACRO .DREND NAME .FORCE = .PSECT 

IF B < PSECT > 

PSECT NAME'DVR 

IFF 

PSECT PSECT 

ENDC 

IIF NDF NAME'$END. NAME'$END:: 

IF EQ .-NAME'$END 
NAME'$END! ! 

,IF NE MMG$T!<F0RCE&2. > 
$RLPTR: : .WORD 
$MPPTR: ! .WORD 
$GTBYT! ! .WORD 
$PTBYT: : .WORD 
$PTWRD: : .WORD 
.ENDC 

.IIF NE ERL*G!<FORCEM>. *ELPTR : : . WORD 
.IIF NE TIM$IT!<FORCE8<4.> . *T IMIT : : . WORD 
*INPTR: ! .WORD 
$FKPTR: 5 .WORD 
.GLOBL NAME'STRT 
NAME'END==. 
.IFF 
.PSECT NAME'BOOT 
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• IIF LT <NAME 'BOOT- . + '~OEBa> t . ERROR !?SYSMAC-E- P r ima rv boot too larSe! 

.=NAME'B00T+-^0BB4 

BIOERR: JSR Rl (REPORT 

.WORD lOERR-NAME'BOOT 

REPORT: MOU #BOOTF-NAME 'BOOT »R0 

JSR Rl (REP 

MOy (Rl)RO 

JSR R1(REP 

MOU #CRLFLF-NAME'BOOT »R0 

JSR RltREP 
RESET 
HALT 

BR .-2. 

REPOR: MOUB (RO)+»@«TPB 

REP! TSTB @#TPS 

BPL REP 

TSTB @R0 

BNE REPOR 

RTS Rl 

BOOTF: .ASCIZ < CR X LF > " ?BOOT-U- "< '^ 0200> 

CRLFLF: .ASCIZ <CR><LF><LF> 

lOERR: .ASCIZ "I/O error" 

.EMEN 
IMAME'BEND: : 

ENDC 

ENDM 



.DRINS 

.DRINS is used to setup the install code area. 
It Generates the CSR(s) words used by INSTALL and RESORC 
It sets the location counter to 200 for the data device 
installation entry point. It optionally Generates words 
containing the second (and more) CSRs supported for handlers 
that support multiple CSRs. It def ines INSDAT =: 200 as 
the label for the data device installation and INSSYB =: 202 
as the label for the system device installation. It defines 
DISCSR as the address of the primary display CSR t INSCSR as the 
address of the installation check CSR t and optionally DISCSn 
where "n" starts at 2 and Sees up as the address(es) of the 
additional display CSRs. For more than 2 CSRs list them within 
< >s . 

.DRINS NAME (CSRS 

.DRINS CR i £fenerate installation code for CR (one CSR) 



■■X77 





.WORD 





DISCSR: 


.WORD 


CR$CSR 


INSCSR: 


.WORD 


CR*CSR 


INSDAT: 






.=202 






INSSYS: 






.=200 








.DRINS 


DX (<DX 


.=170 








.WORD 






end of list 

primary display CSR 

instal 1 CSR 



i for a 2 controller RXOl 



; end of list 
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;discs2 


.WORD 


DX$C52 




JDISCSR 


.WORD 


DX$CSR 




JINSCSR 


.WORD 


DX*CSR 


) 


JINSDAT 








;.=202 








;iNSSYS 








;,=2oo 








5 


.DRINS 


XX .<XX*CS 




;.=iGB 








1 


.WORD 







iDISCS3 


.WORD 


XX$CS3 




;discs2 


.WORD 


XX*CS2 




!DISCSR 


.WORD 


XX*CSR 




5INSCSR 


.WORD 


XX$CSR 




JINSDAT 








5. =202 








;iNSSYS 








i.=200 
1 - 








.MACRO 


.DRINS 


NAME tCSRS 


""1 


.ASECT 






1 


.=-0172 










.WORD 







DISCSR! 


.WORD 


NAME'«CSR 




INSCSR: 


.WORD 


NAME'$CSR 




. . .V2=2 








. . .l^3=''t 


)170 






.IRP X,< 


CSRS> 






.IRP YA 


, , ,VZ 






. = . . .ys 










.WORD 





) 


DISCS'Y 
. ENDR 




.WORD 




. . .y2=. 


.U2+1 






. . .V3=. 


.V3--02 






.ENDR 








. = ^0202 








INSSYS: 








. = '•0200 








INSDAT: 








.ENDM 







secondary display CSR 
primary display CSR 
install CSR 



! for a 3 controller XX99 



5 end of list 
; tertiary display CSR 
! secondary display CSR 
! primary display CSR 
; instal 1 CSR 



.MACRO .DRFIN NAME 
.GLDBL NAME'CQE 



MOU 


PCjR4 


ADD 


»NAME'CQE-, »R4 


MOy 


@»-054>R5 


JMP 


e-0270(R5) 


.ENDM 




.MACRO .DRSET 


OPTION. WAL .RTN .MODE 


.ASECT 




.IF LE .--0400 




, = '-ui\oo 




.IFF 




.=.-2. 




.ENDC 




. . .V2=0 




.IRP X .<UAL> 




.IIF EO ...y2 .IIF EO <X> .ERROR;?SYSMAC-E-t.' A L Must not be 0. VAL i 


. . .V2=. . .y2+i 




.ENDR 




VAL 
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.RAD50 \QPTION\ 

=. . .vz+a. 

.BYTE <RTN-*0iS00>/2. 
. .V2 = 

IRP X»<MODE> 
IF IDN <X>»<NUM> 
. .V2=. , .V2! '0100 
IFF 

IF IDN <X> ><N0> 
. .V2=, , .^2! '0200 
IFF 

IF IDN <X> »<DCT> 
. .VZ=. . .1^2! "0140 
IFF 

ERROR i?SYSMAC-E-Inualid parameter xj 
ENDC 
ENDC 
ENDC 
ENDR 



.BYTE ...y: 
.WORD 



.ENDM 



.MACRO .DRMTB NAME fVEC » INT .PB = 

.IF NB NAME 

NAME'$MTB!! 

. IFF 

.=.-2. 

.ENDC 

.IIFNE i.iECS:3. .ERROR VEC i?SYSMAC-E-Odd o r inyal i d uec t o r speo i f i e d 5 

.WORD MEC6:'C3. >INT-. ro340! PS>0 
,ENDM 

.MACRO .DSTAT RETSPC tDNAM 

. IF NDF . . ,yi 

.MCALL .MACS 

.MACS 

.ENDC 

...CM5 <DNAM> 

...CMO <RETSPC>»342 

.ENDM 

.MACRO .ELAW AREA . ADDR »CODE 

.IF NDF . . .VI 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA>>30 t3,<C0DE> »<ADDR> tE 

.ENDM 

.MACRO .ELRG AREA t ADDR >CODE 

. IF NDF . . ,M1 

.MCALL .MACS 

. MACS 

.ENDC 

. . .CMS <AREA> ,30 »1 »<CODE> »<ADDR>,E 

.ENDM 

.MACRO .ENTER AREA .CHAN iDBLK ,LEN iSEONUM , CODE 

. IF NDF . . .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

.IF EQ . . .Ml-1 
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..CM5 <CHAN> 

..CMO <DBLK> .<40+AREA> 

IFF 

. .CMl <AREA> ,2 »< CHAN >>< CODE >.<D6LK> 

..CM2 <LEN>»4»>C 



. .CM2 


<SEQNUM> 


.G»E.C 


ENDC 








ENDM 








MACRO 


♦ EXIT 








EMT 




^0350 


ENDM 








MACRO 


.FETCH 




ADDR tDNAM 


IF NDF 


. . .VI 






MCALL 


.MACS 






MACS 








ENDC 








. .CM5 


<DNAM> 






. , CMO 


<ADDR> 


t343 


ENDM 








MACRO 


.FORK 




FKBLK 




JSR 




R5.@$FKPTR 




.WORD 




FKBLK - . 


ENDM 









.MACRO .FPROT AREA »CHAN .DBLK » PR0T = «1 .CODE 

.IF NDF . . .VI 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMl <AREA> .35»<CHAN> >< CODE> .<DBLK > 

...CM2 <PROT> »4 .E» »B 

.ENDM 

.MACRO .GMCX AREA .ADDR »CODE 

. IF NDF . . .VI 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA> .30 >B><CODE> »<ADDR> .E 

.ENDM 

.MACRO .GTIM AREA .ADDR .CODE 

. IF NDF . . ,V1 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA> .17 .0 >< CODE >.< ADDR > .E 

.ENDM 



.MACRO .GTJB 
.IF NDF . . .VI 



AREA .ADDR . JOBBLK .CODE 



.MACS 

.ENDC 

...CMS <AREA> »1B .1 .<CDDE> .<ADDR> 

.IF NB <JOBBLK> 

.IF IDN <JOBBLK>.<ME> 

. . .CM2 »-l ,a,E 

.IFF 

...CM2 <JOBBLK>.^.E 

.ENDC 

.IFF 
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. . .CM2 


*-3. ,ii »E 




.ENDC 






.ENDM 






.MACRO 


.GTLIN 


LINBUF 


.IF NDF 


. . .VI 




.MCALL 


.MACS 




.MACS 






.ENDC 






. . .CMO 


<LINBUF> 




.IF 


NB 


<TYPE> 


. . .CMO 


«3. 




.IFF 






. . .CMO 


»1 




.ENDC 






. . .CMO 


<PRDMPT> 




. . .CMO 


(345 




.ENDM 







.MACRO .GVAL AREA >OFFSE »CODE 

.IF NDF . . .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA> .28 »0 »< CODE> .< OFFSE> .E 

.ENDM 



.MACRO 


.HERR 






Moy 


•'02400.ro 




EMT 


'0374 


.ENDM 






.MACRO 


.HRESE 






EMT 


'0357 


.ENDM 






.MACRO 


.INTEN 


prio.pic 


.IF B PIC 






JSR 


R5»@'054 


.IFF 








MOM 


i»'054 f-(SP) 




JSR 


R5t@(SP)+ 


.ENDC 








.WORD 


'C<PRI0#32.> 


.ENDM 






.MACRO 


.LOCK 






EMT 


'034B 


.ENDM 







.MACRO .LOOKU AREA .CHAN .DBLK .SEONUM .CODE 

.IF NDF . . .VI 

.MCALL .MACS 

.MACS 

J ENDC 

. IF EO . . .Ml-1 

...CMS <CHAN>.<20+AREA> 

.IFF 

. . .CMl <AREA> .1 .< CHAN >.< CODE > .<DBLK> 

...CM2 <SE0NUM>.4.E.C 

.ENDC 

.ENDM 



.MACRO .MAP 
.IF NDF . . .VI 



AREA .ADDR .CODE 
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.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA> »30 ,a »<CODE> »<ADDR> (E 

.ENDM 



.MACRO ,MFPS 
MOM 
ADD 
CALL 

.IIP NB <ADDR> » 

.ENDM 



ADDR 

e*-05/:i.-(SP) 

#"03B2 »(SP) 

@(SP)+ 

MOUB (SP)+,ADDR 



+ + 



.MODULE 

Macro to define a standard identification for all 
modules. 

Inputs: 



Module 1-5 character symbol name 
Release 3 char release identification 
Version 2 char uersion number 
Comment n char title strinS 

TITLE=YES Generate .Title 
TITLE=N0 do not Generate .Title 

IDENT=YES Senerate .Ident 
IDENT=NO do not Generate .Ident 

AUDIT=NO Generate .Audit call 
AUDIT=YES Generate .Audit call 

LIB=NO Generate .Audit Slobal value 
LIB=YES do not Generate .Audit 



(KEDIO) 

(X05) 

(09) 

<I/0 Module> 

(default ) 



(default ) 



(default ) 



(default ) 



GLOBAL 



not specified 



GLOBAL=s(name substitutes Sname for .'Module 

Outputs: 



(default) 



.Title 'Module' - 'Comment' 
.Ident " 'Release '. 'Version '" 
. 'Module ' ==: 'Version '. 
• Audit == : " r 'Release ' 



.MCall .Audit 
.Audit .Audit 



. 'Module 



definition of .NLCSI macro 

•NLCSI TYPE=fPART= 

TYPE=Z Generate .AsciZ (default) 

TYPE=I Generate .Ascil 

PART=ALL venerate std ID (default) 
PART=NAME generate name 
PART = RLSVER Generate re 1 ease & v e rs i on 
PART=PREFIX Generate message prefix 

definition of .RModule macro 



title for module 

ident for module 

uersion ualue symbol Binary 

release ualue symbol Rad50 

Set .Audit definition 
generate audit information 



generate program ID string 



.AsoiZ "KEDIO X05.09 " 
.Ascil "KEDIO X05.09 " 

.Asciz "KEDIO X05.09 " 
.AsciZ "KEDIO" 
.Asciz "X05.09" 
.Asciz "7KEDI0-" 

generate RadSO for 'Module 
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.MACRO 

.MCALL 
. IF 
. IIF 
. IFF 
. IIF 
.ENDC 
. IIF 
,IIF 
.IF 



. R M d u 1 e 



.MODULE MODULE. RELEASE. VERSION. COMMENT. 

TITLE = YES .IDENT = YES .AUDIT = NO .GLOBAL .LIB = NO .MODNAME 
.AUD'IT 



NB <MODNAME> 
IDN ,<TITLE><YES>. 

IDN <TITLE> <YES>. 



.TITLE 'MODNAME' - 'COMMENT' 
.TITLE 'MODULE'- 'COMMENT' 



IDN 
IDN 
NB 



<IDENT> <YES>. 
<LIB> <N0>. 
<GL0BAL> 
'GLOBAL' = =! 'MERSION' . 
.IIF IDN <AUDIT> <YES> .. 
. IFF 

. 'MODULE' = =! 'MERSION'. 
.IIF IDN <AUDIT> <YES>. 
.ENDC 

.NLCSI TYPE=Z.PART=ALL 

IDN <PART> <ALL>. 

IDN <PART> <NAME>. 

IDN <PART> <RLSVER>. .ASCI 'TYPE' 

IDN <PART> <PREFIX>. .ASCI 'TYPE' 



.IDENT "'RELEASE'. 'VERSION'" 
.AUDIT==:'R'RELEASE' 



.AUDIT 



.AUDIT 



GLOBAL' 



MODULE' 



.MACRO 

.IIF 

.IIF 

.IIF 

. IIF 

.ENDM 

.MACRO 



.ASCI 'TYPE' 
.ASCI 'TYPE' 



.RMODULE 

.RAD50 "'MODULE'" 



.ENDM 

. . .V5=-0110 

.ENDM 

.MACRO .MRKT AREA .TIME >CRTN . ID .CODE 

.IF NDF . . .VI 

.MCALL .MACS 

• MACS 

.ENDC 

...CMS <AREA> .18 .0 .<CODE>><TIME> 

...CM2 <CRTN>»a 

...CM2 <ID>,B.E 

.ENDM 

.MACRO .MTATC AREA .ADDR .UNIT .CODE 

.IF NDF . . .VI 

.MCALL .MACS 

.MACS 

.ENDC 

...CMS <AREA> .31 .5 .<CODE> .<ADDR> 

...CM2 <UNIT> .4 .E . >B 

.ENDM 

.MACRO .MTDTC AREA .UNIT .CODE 

. IF NDF . . .VI 

.MCALL .MACS 

■ MACS 

.ENDC 

...CMS <AREA> .31 .B.<CODE> 

...CM2 <UNIT> .4 .E t .B 

,ENDM 



" 'MODULE' 'RELEASE 

" 'MODULE' " 

" 'RELEASE' . 'VERSION' " 



VERSION 



"? 'MODULE 



/ II 



.MACRO .MTGET 
. IF NDF , . .VI 
.MCALL .MACS 
.MACS 
.ENDC 



AREA .ADDR .UNIT .CODE 
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. . .CMG 
. . .CM2 
.ENDM 



<AREA> t31 »1 »<CODE> »<ADDR> 
<UNIT> ,a,E , tB 



AREA .ADDR »UNIT>CHRCNT .CODE 



.MACRO ,MTIN 

.IF NDF . . .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA> t31 .2 t<CODE> ><ADDR; 

...CM2 <UNIT> (4. . »B 

...CM2 <CHRCNT> .5 »E . .B 

.ENDM 



ARE A. ADDR .UNITjCHRCNT .CODE 



.MACRO .MTOUT 

. IF NDF . . .Ul 

.MCALL .MACS 

.MACS 

• ENDC 

. . .CMS <AREA> .31 .3 f<CODE> .<ADDR> 

...CM2 <UNIT> >Z| . . ,B 

...CM2 <CHRCNT> .5 .E . .B 

.ENDM 



.MACRO .MTPRN AREA .ADDR .UNIT .CODE 

.IF NDF . . .Ul 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA> .31 .7 .<CODE> .<ADDR> 

...CM2 <UNIT> .4 >E . .B 

.ENDM 



.IIF MB 


<ADDR> 


. CLR -(SP) 


.IIF NB 


<ADDR> 


. MOMB ADDR.(SP) 




MOU 


@«-054 .-(SP) 




ADD 


#~D3B0 .(SP) 




CALL 


@(SP)+ 


.ENDM 






.MACRO . 


.MTRCT 


AREA .UNIT .CODE 


. IF NDF 


...Ml 




.MCALL , 


.MACS 




.MACS 






.ENDC 






i . . CMS 


<AREA> 


.31 ,a .<CODE> 


. . .CM2 


<UNIT> 


.4.E. .B 


.ENDM 






.MACRO . 


.MTSET 


AREA .ADDR .UNIT .CO 


.IF NDF 


...Ml 




.MCALL . 


.MACS 




.MACS 






.ENDC 







. . .CMS <AREA> .31 .0 .<CODE> .<ADDR> 

...CM2 <UNIT> .4 .E . .B 

.ENDM 

.MACRO .MTSTA AREA .ADDR .CODE 

.IF NDF . . .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA> .31 .8 .<CODE> .<ADDR:> 
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, . ,CM2 


#0 ,a,E 




.ENDM 






.MACRO 


.MWAIT 






MOM 


*" 04400 »R0 




EMT 


'0374 


.ENDM 






.MACRO 


.PEEK 


AREA »ADDR.CODE 


. IF NDF 


. . . U 1 




.MCALL 


.MACS 




.MACS 






.ENDC 






. . .CM€ 


<AREA> 


.28.1 ,<CODE>.<ADDR> .E 


.ENDM 






.MACRO 


.POKE 


AREA .ADDR.MALUE ,COD 


. IF NDF 


. . . U 1 




.MCALL 


.MACS 




.MACS 






.ENDC 






. . .CMS 


<AREA> 


.28 .3><C0DE> »<ADDR> 


. . .CM2 


<ualue: 


::■ . 4 , E 


,ENDM 






.MACRO . 


.PRINT 


ADDR 


.IF NDF 


. . .yi 




.MCALL , 


-MACS 




.MACS 






.ENDC 






. . .CM5 


<ADDR> 


.351 


.ENDM 






.MACRO , 


, PROTE 


AREA. ADDR. CODE 


.IF NDF 


. . . U 1 




.MCALL , 


,MACS 




.MACS 






.ENDC 






. . .CMS 


<AREA> 


.25 .0 .<CODE> .<ADDR> .E 


.ENDM 






.MACRO . 


, PURGE 


CHAN 


. IF NDF 


. , . U 1 




.MCALL , 


,MACS 




.MACS 






.ENDC 






. . .CMS 


<CHAN> 


.3. 


.ENDM 






.MACRO 


.PUAL 


AREA .OFFSE.UALUE.CO 


.IF NDF 


... V 1 




.MCALL , 


.MACS 




.MACS 






.ENDC 






. . .CMS 


<AREA> 


.28 .2.'<C0DE> ;<OFFSE> 


. . .CM2 


<ualue; 


> .4 .E 


.ENDM 







.MACRO .QELDF 

. IIF NDF MMG$T , MMG*T=1 

. IIF NE MMG$T . MMG$'t=1 

O.LINK=0 

O.CSW=2. 

O.BLKN=4. 

Q.FUNC=B. 
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0. JNUM = 7. 

O.UNIT=7. 

O.BUFF='^010 
\ Q.WCNT='-012 
' O.CDMP='Oia 

. IRP X .<LINK iCSW tBLKN iFUNC .JNUM .UNIT .BUFF .WCNT .COMP> 

0*'X = C5. 'X-4 

.ENDR 

.IF EO MMG$T 

O.ELGH=~01B 

.IFF 

Q.PAR=''D1B 

0*PAR='012 

O.ELGH=*024 

.ENDC 

.ENDM 

.MACRO .QSET ADDR .LEN 

.IF NDF .. .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

MOV ADDR.-(SP) 
) ...CMS <LEN>»353 
' .ENDM 

.MACRO .RCTRL 

EMT '0355 
.ENDM 

.MACRO ,RCVD AREA .BUF .WCNT .CRTN = *1 .CODE 

.IF NDF . , ,yi 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CM4 <AREA>.<BUF> .< WCNT> »<CRTN> .22 .<CDDE> 

.ENDM 

.MACRO .RCVDC AREA .BUF .WCNT .CRTN .CODE 

.IF NDF . , .VI 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CM-!) <AREA> »<BUF>f<WCNT> .<CRTN> .22><C0DE> 

.ENDM 

.MACRO .RCVDW AREA .BUF .WCNT .CRTN = #0 .CODE 

.IF NDF . . .Vi 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMa < AREA >>< BUF >.< WCNT >.< CRTN >. 22 »< CODE > 

.ENDM 

.MACRO .RDBBK RGSIZ 
.MCALL .RDBDF 
.RDBDF 

.WORD 

.WORD RGSIZ 

.WORD 
.ENDM 

.MACRO , RDBDF 

R.GID=0 

R.GBIZ=Z. 
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R.GSTS= 
R.GLGH= 
RS,CRR= 
RS.UNM= 
RS.NAL= 
.ENDM 



4. 

6. 

"0100000 

"040000 

"020000 



.MACRO 

.IF NDF 

.MCALL 

.MACS 

.ENDC 

. . .CM7 

.ENDM 



.READ AREA .CHAN fBUF .MCNT .BLK .CRTN = 8l .CODE 

. . .VI 

.MACS 



<AREA> .<CHAN> .<BUF>C .<NCNT> .<BLK> .<CRTN> .8 .<CODE> .200 



.MACRO 

.IF NDF 

.MCALL 

.MACS 

.ENDC 

. , .CM7 

.ENDM 



.READC AREA .CHAN .BUF .WCNT »CRTN .BLK .CODE 

. . .VI 

.MACS 



<AREA>.<CHAN>.<BUF>.<WCNT>.<BLK>.<CRTN>.8.<CODE>.200 



.MACRO 

.IF NDF 

.MCALL 

.MACS 

.ENDC 

. . .CM7 

.ENDM 



.READW AREA .CHAN .BUF .WCNT .BLK .CRTN = «0 .CODE 

. . .VI 

.MACS 



<AREA> .<CHAN> .<BUF> .<WCNT> .<BLK> .<CRTN> .8 .<CODE> .200 



.MACRO 
,ENDM 



,REGDEF 



.MACRO 
.IF NDF 
.MCALL 
.MACS 
,ENDC 
. . . CMS 
. . .CMO 
.ENDM 



.RELEA DNAM 
. . .VI 
.MACS 



<DNAM> 
.343 



.MACRO 
.IF NDF 
.MCALL 
.MACS 
.ENDC 
.IF EO 
. . . CMS 
.IFF 
. . .CMl 
.ENDC 
♦ ENDM 



.RENAM AREA. CHAN. DBLK .CODE 

. . .VI 

.MACS 



. . .Vl-1 
<CHAN>.<100+AREA> 

<AREA> .4 .<CHAN> .<CODE> .<DBLK> .E 



.MACRO .REOPE AREA .CHAN .CBLK .CODE 

.IF NDF . . .VI 

.MCALL .MACS 

.MACS 

.ENDC 

.IF EO . . .Vl-1 

...CMS <CHAN>.<140+AREA> 

.IFF 

. . .CMl < AREA >. B. < CHAN >.< CODE >.< CBLK > .E 
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.ENDC 






.ENDM 






.MACRO 


.RSUM 






MOV ■ 


*"01000»R0 




EMT 


"037^ 


.ENDM 







.MACRO .SAVES AREA .CHAN .CBLK »CODE 

.IF NDF . . .VI 

.MCALL .MACS 

.MACS 

.ENDC 

.IF EO . . .Vl-1 

...CMS <CHAN>.<120+AREA> 

.IFF 

. . .CMl <AREA> .5 ><CHAN> .<CODE> .<CBLK > tE 

.ENDC 

.ENDM 



.MACRO .SCCA AREA fADDR .TYPE fCODE 

.IF NDF . . .VI 

.MCALL .MACS 

.MACS 

.ENDC 

.IF NB <TYPE> 

. . .CMG<AREA>,29»1 .<CODE> >< ADDR> .E 

.IFF 

. . .CMS <AREA> f29»0»<C0DE> »<ADDR> >E 

.ENDM 



.MACRO .SDAT AREA »BUF .WCNT »CRTN = «1 , CODE 

.IF NDF . . .VI 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CM4 <AREA> »<BUF>»<WCNT> .<CRTN>>21 .<CODE> 

.ENDM 

.MACRO .SDATC AREA »BUF tWCNT »CRTN .CODE 

.IF NDF . . ,V1 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CM4 <AREA>><BUF>.<WCNT>.<CRTN>.21 »<CODE> 

.ENDM 

.MACRO .SDATW AREA »BUF »WCNT .CRTN = i*0 »CODE 

.IF NDF . . .VI 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CM4 <AREA> »<BUF> j<WCNT> .<CRTN>>21 .<CODE> 

.ENDM 

.MACRO .SDTTM AREA .ADDR .CODE 

.IF NDF . . .VI 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA> .32»0»<CODE> »<ADDR> »E 

.ENDM 



.MACRO .SERR 
MOV 



»'02000,R0 
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EMT "0374 



.ENDM 



.MACRO 


.SETTD AD 


.IF NDF 


. . .VI 


.MCALL 


.MACS 


.MACS 




.ENDC 




. . .CM5 


<ADDR>>354 


.ENDM 





.MACRO .SFDAT AREA f CHAN .DBLK »DATE = «0 »CODE 

.IF NDF . . .VI 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMl < AREA >. 34. < CHAN >»<CODE>.<DBLK> 

...CM2 <DATE>>4»E 

.ENDM 

.MACRO ,SFPA AREA. ADDR. CODE 

. IF NDF . . .VI 

.MCALL .MACS 

.MACS 

.ENDC 

...CMS <AREA>.24»0.<C0DE>.<ADDR>.E 

.ENDM 

i+ + 

i SOB 

i 

; SOB macro is used to retro-fit code written with the SOB 

5 instruction to processors that do not support that instruction. 

; To substitute a uniMersally applicable "SOB"Just .MCALL SOB 



SOB 


R.DST 


DEC 


R 


BNE 


DST 



.MACRO 

.ENDM 

MACRO .SPCPS AREA .ADDR. CODE 

IF NDF . , .VI 

MCALL .MACS 

MACS \ 

ENDC I 

. .CMS < AREA > .33. 0.< CODE >.<ADDR>.E 

ENDM 

MACRO .SPFUN AREA .CHAN .FUND .BUR .WCNT .BLK .CRTN = «0 .CODE 

IF NDF . . .VI 

MCALL .MACS 

MACS 

ENDC 

. .uiii \MiT[CH/- (iD .sunHn^ .suuuc^ »sdi_i\/ 

..CMZ <BUF>.4 

..CM2 <WCNT>.B 

IF NB FUNC 

NTYPE ...V2.FUNC 

IF NE . . ,V2-*027 

IIF DIF <CODE> .NOSET .. . .CM2 8*0377.8. ».B 

..CM2 <FUNC>.3...B 

IFF , 

..CM2 <FUNC'#-04000377>.8 

ENDC \ 
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.ENDC 






. . .CM2 


<CRTN>» 


ICEtC 


.ENDM 






.MACRO 


.SPND 






MOV 


»*0400»R0 




EMT 


-0374 


.ENDM 






.MACRO 


.SRESE 






EMT 


-0352 


.ENDM 






.MACRO 


.SYNCH 


AREA. PIC 


.IF B PIC 




. IIF NB 


<AREA>. 


MOV AREA.R4 


.IFF 






.IF NB AREA 






Moy 


PC»R4 




ADD 


»AREA-. »R4 


.ENDC 






.ENDC 








MOV 


§«-05a»R5 




JSR 


R5»e-0324(R5) 


.ENDM 






.MACRO 


.TIMIO 


TBKfHI »L0 




JSR 


R5.e$TIMIT 




.MORD 


TBK-. 




.MORD 







.WORD 


HI 




.WORD 


LO 


.ENDM 






.MACRO 


.TLOCK 






MOV 


«-03a00»R0 




EMT 


-0374 


.ENDM 







.MACRO .TRPSE AREA »ADDR .CODE 

.IF NDF , . .VI 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA> .3 .0 f<CODE> »<ADDR> .E 

.ENDM 



.MACRO 


.TTINR 






EMT 


-0340 


.ENDM 






.MACRO 


.TTOUT 






EMT 


-0341 


.ENDM 






.MACRO 


.TTYIN 


CHAR 




EMT 


-0340 




BCS 


.-2. 


.IF NB 


<CHAR> 




.IIF DIF <CHAR> 


.RO. 


.ENDC 






.ENDM 






.MACRO 


.TTYOU 


CHAR 


.IF NDF 


...VI 





MOVB 



RO.CHAR 
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.MCALL. .MACS 
.MACS 
.ENDC 

...CMS <CHAR>>341»B 
BCS .-2, 
.ENDM 

.MACRO .TWAIT AREA iTIME .CODE 

. IF NDF , . .Ul 

.MCALL .MACS 

.MACS 

.ENDC 

...CMS <AREA> >20 tO.<CODE> »<TIME> .E 

.ENDM 

.MACRO .UNLOC 

EMT ^0347 
.ENDM 

.MACRO .UNMAP AREA tADDR .CODE 

. IF NDF . . .Ul 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA> .30 .5 .< CODE> .< ADDR> .E 

.ENDM 

.MACRO .UNPRO AREA .ADDR .CODE 

. IF NDF . . ,V1 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA> .25 .1 ,< CODE >.< ADDR > .E 

.ENDM 

.MACRO .WAIT CHAN 

. IF NDF . . .yi 

.MCALL .MACS 

.MACS 

.ENDC 

. IF EQ . . .Ul-1 

EMT '•0<2^0+CHAN> 
.IFF 
.IF B <CHAN> 

CLR RO 
. IFF 

.NTYPE . . .V2 .CHAN 
. IF EQ . . .y2--027 
.IF IDN <CHAN>.#0 

CLR RO 
. IFF 
.IIF IDN <CHAN>. <0>. . ERROR !?SYSMAC-W- Inual i d arSuwent. use #0. not 0! 

MOM CHAN.RO 
.ENDC 
.IFF 



.ENDC 
.ENDC 

.ENDC 
.ENDM 



CLR RO 
BISB CHAN.RO 



EMT '•0374 
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.MACRO .WDBBK 
.MCALL .WDBDF 
.WDBDF 



MNAPR >MNSIZ »MNRID *MNOFF tWNLEN >MNSTS 





.BYTE 






.BYTE 


NNAPR 




.MORD 






.MORD 


MNSIZ 




.MORD 


NNRID 




.MORD 


HNOFF 




.MORD 


MNLEN 




.MORD 


WNSTS 


♦ ENDM 






.MACRO 


.WDBDF 




W.NID=0 






W.NAPR= 


1 




W.NBAS= 


2. 




W.NSIZ= 


4. 




W.NRID= 


6. 




W.NOFF= 


"010 




W.NLEN= 


"012 




W.NSTS= 


"014 




W,NLGH= 


"OIB 




MS.CRM= 


"0100000 




MS.UNM= 


"040000 




MS.ELI«I = 


"020000 




WS.MAP= 


"0400 




.ENDM 






.MACRO 


.WRITC 


AREA .CHAN .BUF .WCNT »CRTN .BLK .CODE 


.IF NDF 


. ..Vl 




.MCALL 


.MACS 




.MACS 






.ENDC 






. . .CM7 


<AREA> , 


<CHAN> .<BUF> .<WCNT> .<BLK> .<CRTN> .9 .<CODE> .220 


.ENDM 







.MACRO .WRITE AREA .CHAN .BUF .WCNT .BLK .CRTN = «1 .CODE 

.IF NDF . . .VI 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CM7 <AREA> .<CHAN> .<BUF> .<WCNT> .<BLK> .<CRTN> .9 .<CODE> .220 

.ENDM 

.MACRO .WRITW AREA .CHAN .BUF .WCNT .BLK .CRTN = »0 .CODE 

.IF NDF .. .VI 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CM7 <AREA> .<CHAN> .<BUF> .<WCNT> .<BLK> .<CRTN> .9 .<CODE> .220 

.ENDM 
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summary, 1-32 
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using, 1-25 
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summary, 1-65 
Channel allocation 
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Channel numbers 



description, 1-1 1 

system subroutine library, 1-39 
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See CSW 
Character strings 
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passing to subprograms, 1-60 

quoted literals, 1-62 

support in SYSLIB, 1-58 
.CHCOPY programmed request, 2-8 

summary, 1-37 

using, 1-23 

Version 4, 1-29 
.CLEAR graphics macro, A-4 
CLOSE keyboard command 

after .EXIT, 1-25 
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.CLOSE programmed request, 2-10 

not done by .CSISPC, 2-23 

on a protected file, 2-52 

relationship to .CHCOPY, 2-8 
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relationship to .LOOKUP, 2-68 

relationship to .PURGE, 2-93 
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requires device handler, 2-48 

summary, 1-33 
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relationship to ICSI, 3-16 
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summary, 1-62 
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.CMKT programmed request, 2-11 
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summary, 1-33 

using, 1-24 
.CNTXSW programmed request, 2-12 

restrictions, 1-27 

summary, 1-37 

using, 1-16 
Command String Interpreter 

See CSI 
Completion routines 

introduction, 1-21 

restrictions, 1-22, 1-41, 2-2 

system subroutine library, 1-40 
CONCAT system subroutine, 3-4 

summary, 1-58, 1-67 
.CRAW programmed request, 2-14 

relationship to .GMCX, 2-53 
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summary, 1-37 

using, 1-26 
.CRRG programmed request, 2-17 

summary, 1-37 

using, 1-26 
CSI 

implicit .UNLOCK, 2-66 

introduction, 1-18 

options, 2-21 

using, 2-18 
CSI special mode 

See .CSISPC 
.CSIGEN programmed request, 2-18 

compared to .GTLIN, 2-58 

implicit .UNLOCK, 2-66 

relationship to .LOOKUP, 2-68 

summary, 1-33 

using, 1-18 
.CSISPC programmed request, 2-23 

compared to .GTLIN, 2-58 

implicit .UNLOCK, 2-66 

relationship to .SETTOP and USR, 
2-122 

summary, 1-33 

using, 1-19 
.CSTAT programmed request, 2-26 

summary, 1-33 

Version 5, 1-30 
.CSTATUS programmed request 

using, 1-18 
CSW 

bits defined by .DRDEF, 2-36 
.CTIMIO macro, 2-27 

expansion, 2-28 

relationship to .DRDEF, 2-35 

summary, 1-33 
.CTIMIO programmed request 

using, 1-24 
CTRL/C 

disabling, 2—115 
CTRL/0 

reset by .RCTRLO, 2-97 
CVTTIM system subroutine, 3-5 

instead of .GTIM, 2-55 

summary, 1-64 

using, 1-57 

Date 

.GTIM required for date 
rollover, 2-55 

internal format, 2-28 

month and year rollover, 2-28 

set by .SDTTM, 2-120 
.DATE programmed request, 2-28 

summary, 1-33 



using, 1-18 
DATE subroutine (in FORLIB) 

using, 1-57 
.DELETE programmed request, 2-29 

on a protected file, 2-52 

requires device handler, 2-48 

summary, 1-33 

using, 1-19 
Device blocks 

description, 1-12 

with system subroutine library, 
1-42 
Device handler macros 

.CTIMIO, 2-27 

.DRAST, 2-32 

.DRBEG, 2-34 

.DRBOT, 2-34 

.DREND, 2-36 

.DRFIN, 2-37 

.DRINS, 2-37 

.DRSET, 2-38 

.DRVTB, 2-39 

.FORK, 2-50 

.INTEN, 2-64 

.SYNCH, 2-136 

.TIMIO, 2-138 
Device handlers 

writing, 1-27 
Device identification codes 

list of values, 2-40 
.DEVICE programmed request, 2-30 

summary, 1-37 

using, 1-17 
Device status word 

contents, 2-40 

defined by .DRDEF, 2-35 
DEVICE system subroutine, 3-5 

relationship to INTSET, 3-29 

summary, 1-65 
DHALT display halt instruction, 

A-14 
Display file handler 

assembling graphics programs, 
A-16 

assembly instructions, A-24 

description, A-1 

example, A-27 

linking, A-16 

linking graphics programs, A-16 

subroutine summary, A-21 

using, A-15 
Display file structure, A-17 

BASIC-11 graphics software, 
A-20 

subroutine calls, A-1 8 
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Display processor mnemonics, A-23 
DJFLT system subroutine, 3-6 

summary, 1-66 

using, 1-57 
DJSR subroutine call instruction, 

A-13 
DNAME load name register 

instruction, A-14 
.DRAST macro, 2-32 

relationship to .DRDEF, 2-35 

relationship to .FORK, 2-51 

summary, 1-33 

using, 1-27 
.DRBEG macro, 2-34 

relationship to .DRDEF, 2-35 

relationship to .DRVTB, 2-39 

relationship to .FORK, 2-51 

summary, 1-33 

using, 1-27 
.DRBOT macro, 2-34 

relationship to .DRDEF, 2-35 

summary, 1-33 

using, 1-27 
.DRDEF macro, 2-35 

summary, 1-33 

use before .DRBEG, 2-34 

used with .TIMIO/.CTIMIO, 1-24 

using, 1-27 
.DREND macro, 2-36 

called by .DRBOT, 2-34 

relationship to .DRDEF, 2-35 

relationship to .DRVTB, 2-39 

relationship to .FORK, 2-51 

summary, 1-33 

using, 1-27 
DRET subroutine return 
instruction, A-13 
.DRFIN macro, 2-37 

relationship to .DRDEF, 2-35 

relationship to .FORK, 2-51 

summary, 1-33 

using, 1-27 
.DRINS macro, 2-37 

relationship to .DRDEF, 2-35 

summary, 1-33 

using, 1-28 
.DRSET macro, 2-38 

relationship to .DRDEF, 2-35 

summary, 1-33 

using, 1-28 
.DRVTB macro, 2-39 

relationship to .DRDEF, 2-35 

summary, 1-33 

using, 1-28 



DSTAT display status instruction, 

A-14 
.DSTATUS programmed request, 2-40 
relationship to .SETTOP and USR, 

2-122 
summary, 1-33 
using, 1-18 

.ELAW programmed request, 2-42 

relationship to .CRAW, 2-15 

summary, 1-37 

using, 1-26 
$ELPTR 

defined by .DREND, 2-36 
.ELRG, 2-17 
.ELRG programmed request, 2-43 

summary, 1-37 

using, 1-26 
EMT codes 

See also Programmed requests 

EMT 374, 1-7 

EMT 375, 1-8 

meaning of different values, 1-3 
EMT instructions 

See Programmed requests 
.ENTER programmed request, 2-43 

done by .CSIGEN, 2-18 

not done by .CSISPC, 2-23 

on a protected file, 2-52 

relationship to .CHCOPY, 2-9 

relationship to .CLOSE, 2-10 

relationship to .CSTAT, 2-26 

relationship to .READx, 2-103 

relationship to .SAVESTATUS, 
2-112 

relationship to .SERR, 2-61 

relationship to .SRESET, 2-135 

relationship to .WRITx, 2-152 

requires device handler, 2-48 

summary, 1-33 

using, 1-19 
EOF$ 

defined by .DRDEF, 2-36 
ERL$G 

defined by .DRDEF, 2-35 
$ERLOG pointer 

in handler termination table, 
2-36 
Error processing 

monitor errors, 1-17 
Errors 

intercepting monitor errors, 
2-141 

programmed requests, 1-12 
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.EXIT programmed request, 2-46 

relationship to .DEVICE, 2-30 

svmimary, 1-33 

using, 1-25 
Extended memory monitor 

See XM monitor 



FB monitor 

foreground job and .FETCH, 2-48 

introduction, 1-2 
.FETCH programmed request, 2-48 

done by .CSIGEN, 2-18 

fills in $FKPTR, 2-51 

not done by .CSISPC, 2-23 

relationship to $INPTR, 2-32 

relationship to .ENTER, 2-45 

relationship to .SETTOP and USR, 
2-122 

relationship to .SRESET, 2-135 

relationship to handler 
termination table, 2-37 

summary, 1-33 

Version 5, 1-30 
File operations 

introduction, 1-19 
FILST$ 

defined by .DRDEF, 2-35 
$FKPTR 

defined by .DREND, 2-36 

setup by user program, 2-52 
Foreground/background 

communications, 1-23 

context switch, 1-23 

with FORTRAN programs, 1-53 
Foreground/background monitor 

See FB monitor 
.FORK macro, 2-50 

relationship to .DRDEF, 2-35 

summary, 1-34 
$FORK pointer 

in handler termination table, 
2-36 
FORLIB.OBJ 

linking, 1-56 
FORTRAN logical units 

relationship to .CHAIN, 2-7 
FORTRAN programs 

calculating workspace, 1-54 
.FPROT programmed request, 2-52 

relationship to .RENAME, 2-110 

requires device handler, 2-48 

summary, 1-34 

using, 1-20 



General mode 

See .CSIGEN 
$GETBYT pointer 

in handler termination table, 
2-36 
GET8TR system subroutine, 3-7 

summary, 1-58, 1-67 

USR requirements, 1-43 
.GMCX programmed request, 2-53 

summary, 1-37 

using, 1-26 
Graphics macro calls 

summary, A-21 
GT OFF keyboard command, A-2 
GT ON keyboard command, A-2 
$GTBYT 

defined by .DREND, 2-36 
.GTIM programmed request, 2-54 

summary, 1-34 

using, 1-18 
GTIM system subroutine, 3-7 

summary, 1-64 
.GTJB programmed request, 2-56 

summary, 1-34 

using, 1-18 

Version 4, 1-29 
GTJB system subroutine, 3-8 

summary, 1-65 
.GTLIN programmed request, 2-58 

implicit .UNLOCK, 2-66 

relationship to .SETTOP and USR, 
2-122 

summary, 1-34 

using, 1-19 

Version 5, 1-30 
GTLIN system subroutine, 3-9 

summary, 1-62 

udR requirements, 1—43 
.GVAL programmed request, 2-60 

compared with .PEEK, 2-89 

summary, 1-34 

HDERR$ 
defined by .DRDEF, 2-36 

.HERR nrnsrrflTmnerl remioat. 9_fi1 

summary, 1-34 
using, 1-17 

HNDLR$ 
defined by .DRDEF, 2-35 

.HRESET programmed request, 2-64 
relationship to .CDFN, 2-5 
relationship to .LOOKUP, 2-68 
relationship to .PURGE, 2-93 
relationship to .QSET, 2-95 
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summary, 1-34 
using, 1-25 

I/O operations 

asynchronous, 1-20 

event driven, 1-21 

introduction, 1-20 

synchronous, 1-20 
lABTIO system subroutine, 3-10 

summary, 1-62 
lADDR system subroutine, .3-10 

summary, 1-67 
lAJFLT system subroutine, 3-11 

summary, 1-66 

using, 1-57 
lASIGN system subroutine, 3-11 

summary, 1-64 
ICDFN system subroutine, 3-13 

summary, 1-64 

USR requirements, 1-43 
ICHCPY system subroutine, 3-14 

summary, 1-64 
ICLOSE system subroutine, 3-2 

relationship to lENTER, 3-21 

summary, 1-62 

USR requirements, 1-43 
ICMKT system subroutine, 3-15 

cancelling an ITIMER request, 
3-56 

cancelling ISCHED requests, 3-44 

summary, 1-64 
ICSI system subroutine, 3-16 

summary, 1-64 

using argument from IFETCH, 
3-23 

using with lASIGN, 3-11 

USR requirements, 1-43 
iCoTAi system suuroui-ine, o— xo 

summary, 1-64 
IDATE subroutine (in FORLIB) 

using, 1-57 
IDELET system subroutine, 3-18 

summary, 1-62 

USR requirements, 1-43 
IDJFLT system subroutine, 3-20 

summary, 1-66 

using, 1-57 
IDSTAT system subroutine, 3-20 

summary, 1-65 

USR requirements, 1-43 
lENTER system subroutine, 3-21 

relationship to CLOSE, 3-3 

relationship to ICSI, 3-16 

summary, 1-62 

USR requirements, 1-43 



IFETCH system subroutine, 3-23 

relationship to ICSI, 3-16 

relationship to IDELET, 3-19 

summary, 1-65 

USR requirements, 1-43 
IFPROT system subroutine, 3-23 

summary, 1-62 
IFREEC system subroutine, 3-24 

summary, 1-64 
IGETC system subroutine, 3-24 

summary, 1-64 
IGETSP system subroutine, 3-25 

summary, 1-67 
IGTJB system subroutine, 3-8 

summary, 1-65 
IJCVT system subroutine, 3-26 

summary, 1-66 

using, 1-57 
ILUN system subroutine, 3-26 

summary, 1-64 
INDEX system subroutine, 3-27 

summary, 1-59, 1-67 
Indirect command files 

relationsip to .CSIGEN, 2-19 
$INPTR 

defined by .DREND, 2-36 

referenced by .DRAST, 2-32 
Input/output operations 

See I/O operations 
INSERT system subroutine, 3-27 

summary, 1-59, 1-67 
.INSRT graphics macro, A-5 
INSTALL keyboard command 

relationship to .DRINS, 2-37 
INTEGER*4 support 

in SYSLIB, 1-57 
.INTEN macro, 2-64 

must precede .FORK, 2-51 

relationship to .SPND/.RSUM, 
2-134 

summary, 1-34 

using, 1-27 
$INTEN monitor routine 

referenced by .DRAST, 2-32 
SINTEN pointer 

in handler termination table, 
2-36 
Interrupt service routines, 1-27 

use of .SYNCH, 2-136 
INTSET system subroutine, 3-28 

summary, 1-67 
IPEEK system subroutine, 3-30 
restrictions, 1-46 
summary, 1-67 
using with IGETSP, 3-25 
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IPEEKB system subroutine, 3-30 

restrictions, 1-46 

summary, 1-68 
IPOKE system subroutine, 3-31 

restrictions, 1-46 

summary, 1-68 

using with IGETSP, 3-25 
IPOKEB system subroutine, 3-31 

restrictions, 1-46 

summary, 1-68 
IPUT system subroutine, 3-32 

summary, 1-68 
IQSET system subroutine, 3-32 

summary, 1-65 

using, 1-46 

USR requirements, 1-43 
IRAD50 system subroutine, 3-33 

summary, 1-67 

using, 1-58 
IRCVD system subroutine, 3-33 

requires queue element, 1-46 

summary, 1-62 
IRCVDC system, subroutine, 3-33 

requires queue element, 1-46 

summary, 1-62 
IRCVDF system subroutine, 3-33 

requires queue element, 1-46 

summary, 1-62 
IRCVDW system subroutine, 3-33 

requires queue element, 1-46 

summary, 1-62 
IREAD system subroutine, 3-35 

requires queue element, 1-46 

summary, 1-62 
IREADC system subroutine, 3-35 

requires queue element, 1-46 

summary, 1-63 
IREADF system^ subroutine, 3-35 

requires queue element, 1-46 

summary, 1-63 
IREADW system subroutine, 3-35 

requires queue element, 1^6 

summary, 1-63 
IRENAM system subroutine, 3-40 

summary, 1-62 

USR requirements, 1-43 
IREOPN system subroutine, 3-41 

summary, 1-64 
ISAVES system subroutine, 3-42 

relationship to IREOPN, 3-41 

summary, 1-64 
ISCHED system subroutine, 3-43 

cancelled by ICMKT, 3-15 

requires queue element, 1-46 

summary, 1-64 



ISCOMP system subroutine, 3-89 

summary, 1-67 
ISDAT system subroutine, 3-44 

requires queue element, 1-46 

summary, 1-63 
ISDATC system subroutine, 3-44 

requires queue element, 1-46 

summary, 1-63 
ISDATF system subroutine, 3-44 

requires queue element, 1-46 

summary, 1-63 
ISDATW system subroutine, 3-44 

requires queue element, 1-46 

summary, 1-63 
ISDTTM system subroutine, 3-47 

summary, 1-64 
ISFDAT system subroutine, 3-47 

summary, 1-62 
ISLEEP system subroutine, 3-48 

requires queue element, 1-46 

summary, 1-65 

using, 1-57 
ISPFN system subroutine, 3-49 

requires queue element, 1-46 

summary, 1-65 
ISPFNC system subroutine, 3-49, 
3-51 

requires queue element, 1-46 

summary, 1-65 
ISPFNF system subroutine, 3-49, 
3-52 

requires queue element, 1-46 

summary, 1-65 
ISPFNW system subroutine, 3-49, 
3-53 

requires queue element, 1-46 

summary, 1-65 
xbi X system suuroutine, 3—55 

restrictions, 1-46 

summary, 1-68 
ISR 

See Interrupt service routines 
ITIMER system subroutine, 3-55 

cancelled by ICMKT, 3-15 

requires nueue element 1—46 

rescheduling FORTRAN 

subroutines, 3-44 

summary, 1-65 
ITLOCK system subroutine, 3-57 

summary, 1-65 

using, 1—45 

USR requirements, 1-43 
ITTINR system subroutine, 3-57 

multiterminal equivalent, 3-79 

summary, 1-63 
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ITTOUR system subroutine, 3-59 

multiterminal equivalent, 3-80 

summary, 1-63 
ITWAIT system subroutine, 3-59 

relationship to SUSPND/RESUME, 
3-93 

requires queue element, 1-46 

summary, 1-65 

using, 1-57 
lUNTIL system subroutine, 3-60 

requires queue element, 1-46 

summary, 1-65 

using, 1-57 
IVERIF system subroutine 

See VERIFY system subroutine 

summary, 1-67 
IWAIT system subroutine, 3-61 

summary, 1-63 

use with ISPFN, 3^9 
IWRITC system subroutine, 3-61, 
3-62 

requires queue element, 1-46 

summary, 1-63 
IWRITE system subroutine, 3-61 

requires queue element, 1-46 

svmimary, 1-63 
IWRITF system subroutine, 3-61, 
3-63 

requires queue element, 1-46 

summary, 1-63 
IWRITW system subroutine, 3-61, 
3-64 

requires queue element, 1-46 

summary, 1-63 

JADD system subroutine, 3-64 

summary, 1-66 
JAFIX system subroutine, 3-65 

summary, 1-66 

using, 1-57 
JCMP system subroutine, 3-65 

summary, 1-66 
JDFIX system subroutine, 3-66 

summary, 1-66 

nair»rp 1 K7 

JDIV system subroutine, 3-67 

summary, 1-66 
JICVT system subroutine, 3-67 

summary, 1-66 

using, 1-57 
JJCVT system subroutine, 3-68 

summaiy, 1-66 
JMOV system subroutine, 3-68 

summary, 1-66 
JMUL system subroutine, 3-69 



summary, 1-66 
Job status word 

See JSW 
JSUB system subroutine, 3-69 

summary, 1-66 
JSW 
bit 11, 2-47 
bit 12, 1-23 
effect on terminal input, 

2-143 
relationship to ITTINR, 3-57 
bit 14, 2-58 
effect on terminal input, 

2-144 
relationship to ITTINR, 3-58 
bit 3, 2-58 
bit 4, 2-144 
bit 5, 2-47 
bit 6 
compared with M.TSTS bit 6, 

2-82 
relationship to .TTINR, 2-143 
relationship to .TTOUTR, 

2-145 
relationship to ITTINR, 3-57 
relationship to ITTOUR, 3-59 
bit 8, 2-7 

issue .MTRCTO or .RCTRLO after 
changing, 2-98 
JTIME system subroutine, 3-70 
summary, 1-65 
using, 1-57 

Keyword macro arguments 
description, 1-11 

LEN system subroutine, 3-71 

summary, 1-59, 1-67 
.LNKRT graphics macro, A-5 
LOAD keyboard command 

before running foreground job, 
2-48 

fills in $FKPTR, 2-51 

relationship to .SRESET, 2-135 

_o j_ _ 

termination table, 2-37 

relationship to IDELET, 3-19 
.LOCK programmed request, 2-65 

compared to .TLOCK, 2-140 

effect of .EXIT, 2-47 

relationship to .CSIGEN, 2-23 

summary, 1-34 

using, 1-16 
LOCK system subroutine, 3-71 

summary, 1-65 
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USR requirements, 1^3 

Logical job names, 2-70 
assigning, 1-25 

.LOOKUP programmed request, 2-68 
done by .CSIGEN, 2-18 
not done by .CSISPC, 2-23 
on a protected file, 2-52 
relationship to .CLOSE, 2-10 
relationship to .CSTAT, 2-26 
relationship to .ENTER, 2-45 
relationship to .READx, 2-103 
relationship to .REOPEN, 2-111 
relationship to .SAVESTATUS, 

2-112, 2-113 
relationship to .SERR, 2-61 
relationship to .WRITx, 2-152 
requires device handler, 2-48 
summary, 1-34 
system job, 2-70 
using, 1-19 
Version 4, 1-29 

LOOKUP system subroutine, 3-73 
relationship to CLOSE, 3-3 
relationship to ICSI, 3-16 
summary, 1-62 
USR requirements, 1-43 

.LPEN graphics macro, A-7 

M.FCNT 

contents, 2-80 
M.TFIL 

contents, 2-80 
M.TST2 

contents, 2-81 

in multiterminal status block, 
2-80 
M.TSTS 

bit 12 
relationship to .MTIN, 2-82 

bite 

relationship to .MTIN, 2-82 
relationship to .MTOUT, 2-83 

contents, 2-80 
M.TSTW 

contents, 2-81 

in multiterminal status block, 
2-80 
M.TWID 

contents, 2-80 
.MAP programmed request, 2-71 

summary, 1-37 

using, 1-26 
MAXJOB 

in timer block, 2-27 
.MCALL directive 



use, 1-6 
Memory allocation 

swapping USR, 1-15 

with .SETTOP, 1-15 
Message handler 

See MQ handler 
.MFPS programmed request, 2-72 

summary, 1-34 

using, 1-18 
MMG$T 

defined by .DRDEF, 2-35 
Monitor fixed offset area 

introduction, 1-3 
Monitor services 

introduction, 1-1 
$MPPHY pointer 

in handler termination table, 
2-36 
$MPPTR 

defined by .DREND, 2-36 
MQ handler 

relationship to system job 
.LOOKUP, 2-70 

using, 1-25 
.MRKT programmed request, 2-74 

relationship to .CMKT, 2-11 

requires queue element, 2-96 

summary, 1-34 

using, 1-24 
MRKT system subroutine, 3-75 

cancelled by ICMKT, 3-15 

requires queue element, 1^6 

summary, 1-65 
.MTATCH programmed request, 2-76 

relationship to .MTGET, 2-80 

summary, 1-34 

using, 1-23 
MTATCH system subroutine, 3-76 

summary, 1-63 
.MTDTCH programmed request, 2-78 

summary, 1-34 

using, 1-23 
MTDTCH system subroutine, 3-78 

summary, 1-63 
.MTGET programmed request, 2-79 

relationship to .MTATCH, 2-76 

summary, 1-34 

using, 1-18, 1-23 
MTGET system subroutine, 3-79 

summary, 1-63 
.MTIN programmed request, 2-82 

summary, 1-34 

using, 1-23 
MTIN system subroutine, 3-79 

summary, 1-63 
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.MTOUT programmed request, 2-83 

summary, 1-34 

using, 1-23 
MTOUT system subroutine, 3-80 

summary, 1-63 
.MTPRNT programmed request, 2-84 

summary, 1-34 

using, 1-23 
MTPRNT system subroutine, 3-81 

summary, 1-63 
.MTPS programmed request, 2-72 

summary, 1-35 

using, 1-18 
.MTRCTO programmed request, 2-85 

summary, 1-35 
MTRCTO system subroutine, 3-81 

summary, 1-64 
.MTSET programmed request, 2-86 

summary, 1-35 

using, 1-23 
MTSET system subroutine, 3-81 

summary, 1-64 
.MTSTAT programmed request, 2-87 

summary, 1-35 

using, 1-18, 1-23 
MTSTAT system subroutine, 3-82 

summary, 1-64 
Multiterminal feature 

introduction, 1-3 
Multiterminal requests 

introduction, 1-23 
Multiterminal status block 

contents, 2-80 

contents after .MTSET, 2-86 
.MWAIT programmed request, 2-88 

relationship to .RCVDx, 2-99 

relationship to system job 
.LOOKUP, 2-70 

summary, 1-37 

using, 1-23 
MWAIT system subroutine, 3-83 

requires queue element, 1-46 

summary, 1-64 



MAA/TTT*. m«or>V»il/»o rr%Qnif*r\ 



A_« 



.NOSYN graphics macro, A-11 

.PEEK programmed request, 2-89 

summary, 1-35 
.POKE programmed request, 2-89 

summary, 1-35 
.PRINT programmed request, 2-90 

multiterminal equivalent, 2-84 

summary, 1-35 

using, 1-22 



PRINT system subroutine, 3-83 

summary, 1-64 
Processor status word 

See PSW 
Programmed requests 

See also EMT codes 

addressing modes, 1-10 

blank arguments, 1-9 

channel numbers, 1-11 

conversion to Version 5, 1-30 

device blocks, 1-12 

errors, 1-12 

execution, 1-4 

extended memory, 1-26 

format, 1-6 

introduction, 1-1, 1-3 

keyword macro arguments, 1-11 

registers available, 1-11 

summary, 1-32 

using, 1-15 

USR requirements, 1-13 

Version 1, 1-28 

Version 2, 1-28 

Version 3, 1-29 

Version 4, 1-29 

Version 5, 1-29 
.PROTECT programmed request, 2-91 

summary, 1-37 

using, 1-17 
PSW 

referenced by .MFPS/.MTPS, 2-72 
$PTBYT 

defined by .DREND, 2-36 
$PTWRD 

defined by .DREND, 2-36 
.PURGE programmed request, 2-93 

relationship to .CHCOPY, 2-8 

relationship to .LOOKUP, 2-68 

relationship to .SERR, 2-61 

summary, 1-35 

using, 1-19 
PURGE system subroutine, 3-84 

in place of CLOSE, 3-3 
$PUTBYT pointer 

.LAJl ^J.tAAAXAJ.VJ. U\^J. XJ.J.XXACAUAV/J.X UUILTX^^j 

2-36 
PUTSTR system subroutine, 3-84 

summary, 1-58, 1-67 

USR requirements, 1-43 
$PUTWRD pointer 

in handler termination table, 
2-36 
.PVAL programmed request, 2-60 

compared with .POKE, 2-89 

summary, 1-35 
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to change default .ENTER size, 
2-44 

Q$BLKN 

defined by .QELDF, 2-95 
Q$BUFF 

defined by .QELDF, 2-95 
Q$COMP 

defined by .QELDF, 2-95 
Q$CSW 

defined by .QELDF, 2-95 
Q$FUNC 

defined by .QELDF, 2-95 
Q$JNUM 

defined by .QELDF, 2-95 
Q$LINK 

defined by .QELDF, 2-95 
Q$PAR 

defined by .QELDF, 2-95 
Q$UNIT 

defined by .QELDF, 2-95 
Q$WCNT 

defined by .QELDF, 2-95 
Q.BLKN 

defined by .QELDF, 2-94 
Q.BUFF 

defined by .QELDF, 2-95 
Q.COMP 

defined by .QELDF, 2-95 

relationship to .SYNCH, 2-137 
Q.CSW 

defined by .QELDF, 2-94 
Q.ELGH 

defined by .QELDF, 2-95 
Q.FUNC 

defined by .QELDF, 2-95 
Q.JNUM 

defined by .QELDF, 2-95 
Q.LINK 

defined by .QELDF, 2-94 
Q.PAR 

defined by .QELDF, 2-95 
Q.UNIT 

defined by .QELDF, 2-95 
Q.WCNT 

defined by .QELDF, 2-95 
.QELDF macro, 2-94 

relationship to .DRDEF, 2-35 

relationship to .FORK, 2-51 

summary, 1-35 
.QSET programmed request, 2-95 

effect of .EXIT, 2-47 

relationship to .RCVDx, 2-98 

relationship to .READx, 2-103 

relationship to .SRESET, 2-135 



relationship to .TWAIT, 2-147 
relationship to .WRITx, 2-152 
restrictions, 1-27 
summary, 1-35 
using, 1—16 

R.GID 

defined by .RDBDF, 2-102 
R.GLGH 

defined by .RDBDF, 2-102 
R.GSIZ 

defined by .RDBDF, 2-102 
R.GSTS 

defined by .RDBDF, 2-102 
R50ASC system subroutine, 3-85 

summary, 1-67 

using, 1-58 
RAD50 system subroutine, 3-85 

summary, 1-67 

using, 1-58 
Radix-50 support 

in SYSLIB, 1-58 
RCHAIN system subroutine, 3-86 

relationship to CHAIN, 3-2 

summary, 1-66 
.RCTRLO programmed request, 2-97 

multiterminal equivalent, 2-85 

summary, 1-35 

using, 1-22 
RCTRLO system subroutine, 3-86 

multiterminal equivalent, 3-81 

summary, 1-66 
.RCVD programmed request, 2-98 

relationship to .SDATx, 2-116 

relationship to system job 
.LOOKUP, 2-70 

requires queue element, 2-96 

summary, 1-37 

use with .MWAIT, 2-88 

using, 1-23, 1-25 
.RCVDC programmed request, 2-98 

relationship to .SDATx, 2-116 

requires queue element, 2-96 

summary, 1-37 

using, 1-23 
.RCVDW programmed request, 2-98 

relationship to .SDATx, 2-116 

requires queue element, 2-96 

summary, 1-37 
.RDBBK macro, 2-102 

summary, 1-37 

using, 1-26 
.RDBDF macro, 2-102 

summary, 1-37 

using, 1-26 
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.READ programmed request, 2-102 

for messages between jobs, 2-70 

relationship to .SAVESTATUS, 
2-113 

relationship to .SPFUN, 2-130 

relationship to .CHCOPY, 2-8 

requires device handler, 2-48 

requires queue element, 2-96 

summary, 1-35 

use with .WAIT, 2-149 

using, 1-20, 1-25 
.READC programmed request, 2-102 

for messages between jobs, 2-70 

requires device handler, 2-48 

requires queue element, 2-96 

summary, 1-35 

using, 1-21 
.READW programmed request, 2-102 

for messages between jobs, 2-70 

requires device handler, 2-48 

requires queue element, 2-96 

summary, 1-35 

using, 1-20 
REENTER keyboard command 

after .EXIT, 1-25 

relationship to .EXIT, 2-46 
.RELEASE programmed request, 2-48 

after .FETCH, 2-49 

sometimes ignored, 2-49 

summary, 1-35 
$RELOC pointer 

in handler termination table, 
2-36 
.REMOV graphics macro, A-9 
.RENAME programmed request, 2-110 

on a protected file, 2-52 

requires device handler, 2-48 

summary, 1-35 

using, 1-19 
.REOPEN programmed request, 2-111 

summary, 1-35 

using, 1-19 
REPEAT system subroutine, 3-87 

summary, 1-59, 1-67 
RESORC utility 

relationship to .DRINS, 2-37 
.RESTR graphics macro, A-9 
RESUME system subroutine, 3-87 

relationship to SUSPND, 3-93 

summary, 1-66 
$RLPTR 

defined by .DREND, 2-36 
RONLY$ 

defined by .DRDEF, 2-35 
RS.CRR 



defined by .RDBDF, 2-102 
RS.NAL 

defined by .RDBDF, 2-102 
RS.UNM 

defined by .RDBDF, 2-102 
.RSUM programmed request, 2-133 

effect of .TWAIT, 2-147 

relationship to .SRESET, 2-135 

summary, 1-38 

.SAVESTATUS programmed request, 
2-112 

relationship to .ENTER, 2-45 

relationship to .LOOKUP, 2-68 

relationship to .PURGE, 2-93 

relationship to .REOPEN, 2-111 

summary, 1-35 

using, 1-19 
.SCCA programmed request, 2-115 

summary, 1-35 
SCCA system subroutine, 3-88 

summary, 1-66 
SCOMP system subroutine, 3-89 

summary, 1-59, 1-67 
SCOPY system subroutine, 3-89 

summary, 1-59, 1-67 
.SCROL graphics macro, A-9 
.SDAT programmed request, 2-116 

relationship to .RCVDx, 2-98 

relationship to system job 
.LOOKUP, 2-70 

requires queue element, 2-96 

summary, 1-38 

use with .MWAIT, 2-88 

using, 1-23, 1-25 
.SDATC programmed request, 2-116 

relationship to .RCVDx, 2-98 

requires queue element, 2-96 

summary, 1-38 

using, 1-23 
.SDATW programmed request, 2-116 

relationship to .RCVDx, 2-98 

requires queue element, 2-96 

summary, 1-38 
.auv livi programmea request, jCt-izm 

summary, 1-36 

using, 1-18 
SECNDS system subroutine, 3-90 

instead of .GTIM, 2-55 

summary, 1-65 
.SERR programmed request, 2-61 

error codes, 2-62 

relationship to .DELETE, 2-29 

relationship to. .ENTER, 2-45 

summary, 1-36 
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using, 1-17 
SET keyboard commands 
relationship to .DRSET, 2-38 
SET EXIT NOSWAP 
relationship to .EXIT, 2-46 
relationship to .SETTOP and 
USR, 2-122 
SET EXIT SWAP 

relationship to .EXIT, 2-46 
SET TT QUIET 

relationship to .GTLIN, 2-58 
SET USR NOSWAP 
relationship to .SETTOP, 

2-121 
relationship to LOCK/UNLOCK, 
3-72 
SET option table 

defined by .DRSET, 2-38 
SETCMD system subroutine, 3-91 

summary, 1-66 
.SETTOP programmed request, 2-121 
in XM monitor, 2-123 
restrictions, 1-27 
summary, 1-36 
using, 1-15 
.SFDAT programmed request, 2-125 
relationship to .RENAME, 2-110 
requires device handler, 2-48 
summary, 1-36 
using, 1-20 
.SFPA programmed request, 2-125 
relationship to .CNTXSW, 2-12 
summary, 1-36 
using, 1-17 
Single-job monitor 
See SJ monitor 
Single-line editor 
relationship to .TTYIN, 2-144 
relationship to ITTINR, 3-58 
SJ monitor 

introduction, 1-2 
SOB macro, 2-127 
summary, 1-36 
.SPCPS programmed request, 2-127 






using, 1-22 
Special (single-character) mode 

for terminal, 1-23 
Special function codes, 3-50 
SPECL$ 

defined by .DRDEF, 2-35 
.SPFUN programmed request, 2-129 

bit in device status word, 2-41 

function codes, 2-130 

requires device handler, 2-48 



summary, 1-36 

using, 1-17 
SPFUN$ 

defined by .DRDEF, 2-35 
.SPND programmed request, 2-133 

effect of .TWAIT, 2-147 

relationship to .SRESET, 2-135 

summary, 1-38 

using, 1-25 
.SRESET programmed request, 2-135 

performed by .HRESET, 2-64 

relationship to .CDFN, 2-5 

relationship to .LOOKUP, 2-68 

relationship to .PURGE, 2-93 

relationship to .QSET, 2-95 

summary, 1-36 

using, 1-25 
Stack pointer 

caution with .CHAIN, 2-7 

during .EXIT, 2-47 
.START graphics macro, A-10 
START keyboard command 

after .EXIT, 1-25 

relationship to .EXIT, 2-46 
.STAT graphics macro, A-10 
.STOP graphics macro, A-11 
STRPAD system subroutine, 3-91 

summary, 1-59, 1-67 
SUBSTR system subroutine, 3-92 

summary, 1-59, 1-67 
Suspension of a program, 1-25 
SUSPND system subroutine, 3-93 

relationship to RESUME, 3-87 

summary, 1-66 
.SYNC graphics macro, A-11 
.SYNCH macro, 2-136 

relationship to .SPND/.RSUM, 
2-134 

summary, 1-36 

using, 1-21, 1-27 
SYSCOM area 

introduction, 1-3 
SYSLIB functions, 3-1 

channel, 1-64 
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data transfer, 1-62 
date and time, 1-57 
device and file, 1-64 
file-oriented, 1-62 
INTEGER*4, 1-42, 1-57, 1-66 
miscellaneous, 1-67 
program suspension, 1-57 
Radix-50, 1-58, 1-67 
RT-11 services, 1-65 
summary, 1-62 
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timer, 1-64 
SYSLIB.OBJ 

additional services, 1-56 

introduction, 1-1 
SYSLOW, 2-124 
SYSMACMAC 

from SYSMAC.SML, 1-1 

listing, B-1 
SYSMAC.SML 

description, 1-6 

introduction, 1-1 

macros for device handlers, 
1-27 

macros for interrupt service 
routines, 1-27 

splitting to get SYSMACMAC, 
1-1 
System communication area 

See SYSCOM area 
System job support 

introduction, 1-3 
System jobs 

communicating with, 1-25 

.LOOKUP, 2-70 
System macro library 

introduction, 1-1 

listing, B-1 
System status 

how to get, 1-18 
System subroutine library 

calling conventions, 1-47 

capabilities, 1-38 

channel numbers, 1-39 

completion routines, 1-40 
restrictions, 1-41 

conventions, 1-39 

device blocks, 1-42 

FORTRAN/MACRO interface, 1-48 

introduction, 1-1 

subroutine argument block, 1-48 

subroutine register usage, 1~49 

system restrictions, 1-46 

using, 1-38 



Terminal I/O 



1-22 



special mode, 1-23 
Termination of a program, 1-25 
TIM$IT 

defined by .DRDEF, 2-35 
TIMASC system subroutine, 3-94 

instead of .GTIM, 2-55 

summary, 1-65 

using, 1-57 
Time 



internal format, 2-120 

set by .SDTTM, 2-120 
TIME keyboard command 

relationship to GTIM system 
subroutine, 3-7 
TIME system subroutine, 3-95 

instead of .GTIM, 2-55 

summary, 1-65 
Timer block format, 2-27 
Timer support 

introduction, 1-24 
.TIMIO macro, 2-138 

relationship to .CTIMIO, 2-27 

relationship to .DRDEF, 2-35 

summary, 1-36 

timer block format, 2-27 
$TIMIO pointer 

in handler termination table, 
2-36 
.TIMIO programmed request 

using, 1-24 
$TIMIT 

defined by .DREND, 2-36 
.TLOCK programmed request, 2-140 

summary, 1-36 

using, 1-16 
.TRACK graphics macro, A-11 
TRANSL system subroutine, 3-95 

summary, 1-59, 1-67 
TRIM system subroutine, 3-97 

summary, 1-59, 1-67 
.TRPSET programmed request, 2-141 

summary, 1-36 

using, 1-17 
.TTINR programmed request, 2-143 

summary, 1—36 

using, 1-22 

with indirect command file, 
2-59 
.TTOUTR programmed request, 2-145 

summary, 1-36 

using, 1-22 

when to use .PRINT, 2-90 
.TTYIN programmed request, 2-143 

multiterminal equivalent, 2-82 
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using, 1-22 

with indirect command file, 
2-59 
.TTYOUT programmed request, 2-145 

multiterminnal equivalent, 2-83 

summary, 1-36 

using, 1-22 

when to use .PRINT, 2-90 
.TWAIT programmed request, 2-147 
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relationship to .CMKT, 2-12 
relationship to .SPND/.RSUM, 

2-133 
requires queue element, 2-96 
summary, 1-36 
using, 1-24 
Version 5, 1-30 

.UNLNK graphics macro, A-12 
.UNLOCK programmed request, 2-65 

implicit by .CSIGEN, 2-18, 2-23 

implicit by .CSISPC, 2-24 

performed by .EXIT, 2-47 

summary, 1-36 

using, 1-16 
UNLOCK system subroutine, 3-97 

relationship to LOCK, 3-71 

summary, 1-66 
.UNMAP programmed request, 2-148 

relationship to .MAP, 2-71 

summary, 1-38 

using, 1-26 
.UNPROTECT programmed request, 
2-91 

summary, 1-38 

using, 1-17 
User service routine 

See USE 
USR 

ownership by different jobs, 
2-140 
USR locking 

effect of .LOCK, 2-65 

effect of UNLOCK system 
subroutine, 3-97 

how to minimize, 1-45 

relationship to .CSIGEN, 2-18 

using LOCK system subroutine, 
3-71 
USR requirements 

.CLOSE, 2-10 

FORTRAN interface, 1-43 

programmed requests, 1-13 

swapping, 1-14 
USR swapping 
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effect of .LOCK, 2-65 

strategies, 1-44 

..VI.. macro 

summary, 1-36 
..V2.. macro 

summary, 1-36 
VARSZ$ 

defined by .DRDEF, 2-35 



VERIFY system subroutine, 3-98 

summary, 1-59, 1-67 
Version 1 

differences, 1-28 
Version 2 

differences, 1-28 
Version 3 

differences, 1-29 
Version 4 

differences, 1-29 
Version 5 

differences, 1-29 
VTBASE.OBJ display file handler 

module, A-2, A-15 
VTCALl.OBJ display file handler 

module, A-2, A-15 
VTCAL2.0BJ display file handler 

module, A-2, A-15 
VTCAL3.0BJ display file handler 

module, A-2, A-15 
VTCAL4.0BJ display file handler 

module, A-2, A-15 
VTHDLR.OBJ concatenated display 

modules, A-2, A-16 
VTLIB.OBJ display file handler 
library, A-2, A-15 
components, A-16 
linking, A-16 
VTMAC.MAC 
listing, A-25 
VTMAC.MAC display file handler 
macros, A-2, A-15 

W.NAPR 

defined by .WDBDF, 2-151 

modified by .GMCX, 2-54 

use with .CRAW, 2-14 
W.NBAS 

defined by .WDBDF, 2-151 

modified by .GMCX, 2-54 
W.NID 

defined by .WDBDF, 2-151 
W.NLEN 

defined by .WDBDF, 2-151 

modified by .GMCX, 2-54 
wrxTT.nw 

defined by .WDBDF, 2-151 

W.NOFF 
defined by .WDBDF, 2-151 
modified by .GMCX, 2-54 

W.NRID 
defined by .WDBDF, 2-151 

W.NSIZ 
defined by .WDBDF, 2-151 
modified by .GMCX, 2-54 
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W.NSTS 

defined by .WDBDF, 2-151 

modified by .GMCX, 2-54 

use with .CRAW, 2-14 
W.RID 

modified by .GMCX, 2-54 
.WAIT programmed request, 2-149 

compared with .MWAIT, 2-88 

summary, 1-36 

use with .CSIGEN, 2-18 

use with .READx, 2-104 

using, 1-20 
.WDBBK macro, 2-150 

summary, 1-38 

using, 1-26 
.WDBDF macro, 2-151 

automatically called by .WDBBK, 
2-150 

summary, 1-38 

using, 1-26 
WONLY$ 

defined by .DRDEF, 2-35 
.WRITC programmed request, 2-152 

for messages between jobs, 2-70 

relationship to .CSTAT, 2-26 

requires device handler, 2-48 

requires queue element, 2-96 

summary, 1-36 

using, 1-21 
.WRITE programmed request, 2-152 

for messages between jobs, 2-70 

relationship to .CHCOPY, 2-8 

relationship to .CSTAT, 2-26 

relationship to .SAVESTATUS, 
2-113 



relationship to .SPFUN, 2-130 

requires device handler, 2-48 

requires queue element, 2-96 

summary, 1-37 

to a protected file, 2-52 

use with .WAIT, 2-149 

using, 1-20, 1-25 
.WRITW programmed request, 2-152 

for messages between jobs, 2-70 

relationship to .CSTAT, 2-26 

requires device handler, 2-48 

requires queue element, 2—96 

summary, 1-37 

using, 1-20 
WS.CRW 

defined by .WDBDF, 2-151 

use with .CRAW, 2-14 
WS.ELW 

defined by .WDBDF, 2-151 

use with .CRAW, 2-14 
WS.MAP 

defined by .WDBDF, 2-151 

effect on .CRAW, 2-14, 2-15 

optional argument to .WDBBK, 
2-151 
WS.UNM 

defined by .WDBDF, 2-151 
WS.VNM 

use with .CRAW, 2-14 

XM monitor 
introduction, 1-2 
t5T)es of programmed requests, 

1-26 
using, 1—26 
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HOW TO ORDER 
ADDITIONAL DOCUMENTATION 



From 



Call 



Write 



Chicago 



312-640-5612 

8:15 AM to 5:00 pm CT 



Digital Equipment Corporation 
Accessories & Supplies Center 
1050 East Remington Road 
Schaumburg, IL 60195 



San Francisco 



Alaska, Hawaii 



408-734-4915 

8:15am to 5:00pm PT 

603-884-6660 

8:30 A M to 6:00 p m ET 

or 408-734-4915 

8:15 AM to 500 pm PT 



Digital Equipment Corporation 
Accessories & Supplies Center 
632 Caribbean Drive 
Sunnyvale, CA 94086 



New Hampshire 

Rest of U.S.A., 
Puerto Rico* 



603-884-6660 

8:30 AM to 6:00 pm ET 

1-800-258-1710 

8:30 AM to 6:00 pm ET 



Digital Equipment Corporation 
Accessories & Supplies Center 
P.O. Box CS2008 
Nashua, NH 03061 



"Prepaid orders from Puerto Rico must be placed with the local DIGITAL subsidiary (call 809-754-7575) 



Canada 
British Columbia 

Ottawa-Hull 

Elsewhere 



1-800-267-6146 
8:00 AM. to 5:00 p m ET 

613-234-7726 
8:00 AM to 5:00 p m ET 

112-800-267-6146 
8:00 AM to 5:00 p.m. ET 



Digital Equipment of Canada Ltd 
940 Belfast Road 
Ottawa, Ontario K1G 4C2 
Attn: A&SG Business Manager 



Elsewhere 



Digital Equipment Corporation 
A&SG Business l^anager* 



'c/o DIGITAL'S local subsidiary or approved distributor 



